Skip to content

Frequently asked questions

Short answers to the questions people ask first. Where a topic deserves more, each answer links to the page that covers it in full.

What's shipped vs. designed

Phases 0–4 are implementation-complete under their supported profiles. Phase 5 is in progress at M5.0 contracts/gates; M5.1-M5.8 remain open. Answers below distinguish runnable capabilities from design targets. See the roadmap.

Getting oriented

Is TOVIO a replacement for Git?

Yes --- that's the goal. TOVIO is a full version control system, not a Git plugin or wrapper. It has its own object store, its own change model, and its own CLI. You can use it as a drop-in for the everyday loop: init, commit, log, diff, lane, switch.

What makes it worth switching is what Git can't do: per-file cryptographic permissions, first-class AI-agent authorization, and change identity that survives history rewriting. If none of those matter to you yet, TOVIO still gives you a cleaner core --- no staging area, local op-log undo for supported recorded mutations, and no "diverged history" errors.

Is it Git-compatible?

In the ways that matter for adoption, yes --- but it is not a drop-in over Git's wire protocol.

  • You can bring a Git repo in. tovio git import <repo> walks the Git history, assigns TOVIO change IDs, and writes the git-hash → change-id map into the repository so the original hashes stay recoverable. See the migration recipe.
  • You can keep Git and TOVIO active together. tovio git bridge <remote> --bidirectional runs a finite two-way cycle. Git branches enter git/<remote-id>/*; TOVIO lanes publish under Git tovio/*; neither native main history is force-pushed.
  • Your muscle memory still works. Git-compat aliases mean add, checkout, branch, stash, and reset do the sensible TOVIO thing and gently point you at the native command. (push and pull are native TOVIO commands in their own right; bare, they hint at sync.)

What TOVIO deliberately does not do is speak Git's wire protocol directly. Interop is via explicit import, export, and bridge --- not a silent pretend-to-be-Git layer.

Do I have to learn a whole new mental model?

Less than you'd expect. The big shifts are: there's no staging area (your working copy is always the current change --- no git add step), and lanes reconcile automatically instead of diverging. Both remove steps rather than add them. The concepts section maps each TOVIO idea to the Git concept you already know.

Hosting & networking

Do I have to host anything?

No. TOVIO is offline-first. Core operations such as commit, lane, diff, log, supported local undo, and conflict resolution work with zero network when the selected object graph and any required local recipient keys are already available. A solo, fully local repository can stay local; sparse, partial, shallow, or lazy profiles may need an authenticated promisor to hydrate missing objects.

A server (the Forge) only enters the picture when you want to collaborate --- share a repo, enforce write policies centrally, or browse an audit log as a team. The single-node Forge is built and hermetically tested; its signed container image and Helm chart are built too, but they are still waiting on clean-registry/cluster and production multi-host evidence. A hosted option belongs to Phase 5. Neither is required to use TOVIO locally.

Does TOVIO phone home? What about telemetry?

The current CLI has no product-analytics uploader or tovio telemetry command. Networked operations still send the protocol data needed for the action you invoke, and a Forge or hosted service has documented operational, audit, billing, and security logs; “no analytics uploader” is not “no network or metadata.”

The marketing and documentation sites can load cookie-free Cloudflare Web Analytics only when their build token is configured. The authenticated app does not inherit that token or script. Any future CLI analytics feature would need an implemented data contract, consent and inspection controls, documentation, and a separate status update before this answer could claim it exists.

Can I run the server on my own infrastructure?

Yes, and it is a first-class deployment model rather than an afterthought --- but the Forge is a commercial product, licensed LicenseRef-TOVIO-Commercial and destined for an entitled distribution channel to dedicated enterprises under agreement --- a channel that is not open yet, so a source build under that licence is today's route. It is a single Rust binary that stores only ciphertext for protected objects and serves the collaboration and audit APIs. Single-node operation is implemented; the release packaging is built but unpublished, and production multi-host verification and HA evidence remain. See the roadmap.

If you want a networked server with no agreement, the Apache-2.0 CLI ships tovio serve: clone, fetch, and push over TLS with the write-policy gate enforced --- complete version control, without the collaboration platform.

Be deliberate about where you run it: tovio serve is a peer-to-peer relay, not a review-gating server. Its connection ACL is open by design --- confidentiality is the cryptography's job, not the transport's --- and lane protection, review requirements, and the audit chain are enforced only at the Forge edge. Anything that can reach the port can push to any lane.

Security & secrets

Can AI agents read my secrets?

Not unless you explicitly grant it. This is the whole point of TOVIO's agent model.

An agent gets a capability token --- a signed certificate that scopes what it can touch: which paths, whether it has secret_clearance, which operations are allowed, and an expiry. An agent without secret_clearance is never handed the key to a protected object, even if the file sits inside its path scope. Out-of-scope access fails on the path check before any decryption is even attempted.

The TOVIO read surface will not disclose content outside that token and key scope. This does not sandbox other tools on the agent's machine or retract plaintext that a human, runner, or prompt explicitly discloses. The agent control plane is implemented across CLI, Node, and MCP; see the AI agents section and the Cursor recipe.

How do per-file permissions actually work?

A protected file is encrypted under a policy before it ever lands in a tracked tree. The content is encrypted once with a random data key; that data key is then wrapped separately for each authorized identity. If your identity doesn't satisfy the policy, no wrapped key exists for you --- so the ciphertext is just noise, even if you hold the entire repository.

The crucial property: the math enforces it, not a server. Someone can clone the whole repo and still not read a file they lack clearance for. Revoking access rotates the data key and re-wraps it for the remaining identities. Tier-0/Tier-1 encryption is implemented; the Security section covers it in depth.

Is my whole repo encrypted, or just some files?

Only what you protect with a policy. Most of a repo is ordinary code that everyone on the team can read; you mark the sensitive paths --- config/prod.env, a credentials directory, a customer dataset --- and those become ciphertext to anyone without clearance. There's no all-or-nothing switch; permissions are per-path by design. See the .env recipe.

What happens if I lose my key?

Key loss is real risk, so TOVIO provides recovery material at init, encrypted key export/import, and tovio key recover to restore decryption after a loss. Guard identity and recovery material as carefully as SSH keys.

Working with TOVIO

What happened to the staging area?

There isn't one, on purpose. Your working copy is continuously snapshotted into the current change; commit finalizes that change and opens the next one. There's no git add step to forget. If you want to split a change into pieces or move work between changes, explicit commands do that --- you just don't pay the staging tax on every commit. See no staging area.

What if I make a mistake? Can I undo?

For supported retained local mutations, yes. TOVIO keeps an operation log, and tovio undo can reverse a botched lane delete, a bad rebase, or a wrong commit; tovio redo reapplies it. Undoing a sync restores local state but does not recall observations from peers. Authenticated obliteration, external service effects, and operations outside local retention are not reversible.

What about big binary files --- do I need something like Git LFS?

No. TOVIO has binary parity built in: large files are split into content-defined chunks, and identical chunks are stored once across the whole repo. A small edit to a 4 GB file re-stores only the chunks that changed. There's no separate large-file extension to install or configure.

Why don't I get "diverged history" errors?

Because lane pointers are CRDTs. When you and a teammate both move a lane offline and later sync, TOVIO reconciles the two automatically --- no force-push, no "your branch and origin have diverged." If the underlying content genuinely conflicts, that conflict is stored as a first-class object you resolve when ready; it never blocks your work in the meantime.

The project

What license is TOVIO under?

TOVIO uses a per-component ("open-core") licensing model, not a single blanket license:

  • The core engine, CLI, and SDKs --- tovio-core, tovio-cli, tovio-proto, tovio-node-bindings, the keystore/index/store crates, and the TypeScript SDKs --- are Apache-2.0 (OSI-approved open source).
  • tovio-forge and tovio-web-ui --- the Forge collaboration server and its web dashboard --- are a proprietary commercial product. Only TOVIO operates the Forge as a service, and only TOVIO distributes the binary. Elastic-2.0 was retired from this project ([ADR-0312]) because it protected only the hosting line: it restricted reselling the Forge as a service, not using it, so the customer most able to pay was entitled to run the whole product for nothing.
  • The free tier is tovio serve, in the Apache-2.0 CLI above --- a real bidirectional TLS server that clones, fetches, pushes, and enforces your per-file permission policy on every push. What it does not carry is the collaboration platform: no proposals, review, checks, merge queue, locks, events, webhooks, or audit chain. A capability boundary, not a licence asterisk.
  • TOVIO Cloud, the private Cloudflare service adapter, enterprise connectors, and enterprise modules (advanced governance, threshold/KMS Key Authority, the managed-service grant) are commercial / proprietary.

"TOVIO" is a trademark of the TOVIO project; none of these licenses grant a right to use the TOVIO name or marks. The authoritative texts are LICENSE and LICENSE-APACHE at the repository root, with the per-component overview in LICENSE. See Contributing.

Where do I report a bug or ask for a feature?

Through the public feedback portal at https://tovio.dev/feedback --- the feedback, roadmap and updates page explains what a useful report contains and how a post becomes a change.

How do I report a security issue?

Anything that could expose protected content, leak a secret, forge a signature, or bypass an enforcement stage is a vulnerability --- do not post it on the feedback portal or in any other public channel. Follow the coordinated-disclosure process on the coordinated-disclosure page. The crypto and permission system is the highest-severity surface in the project, so please treat it that way.

How can I contribute?

Start with the contributing guide. In short: the build and test gates are spelled out, first-time contributors sign the CLA by adding themselves to the in-repo roster, and every commit carries a Signed-off-by: line. New contributors are welcome.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure