Skip to content

The seven concepts

TOVIO has seven things. If you understand these seven, you understand TOVIO — everything in the rest of the documentation is detail underneath them.

  1. An identity — who is acting.
  2. A change — a unit of work.
  3. A commit — a saved snapshot.
  4. A conflict — a question the repo holds for you.
  5. A policy — who may read a path.
  6. A capability — what an agent is allowed to do.
  7. A forge — where people share.

The reason to teach these explicitly is honest: TOVIO introduces more new concepts than Git does. A tool that asks you to learn more has to be worth it, and it has to teach the model rather than leave you to reverse-engineer it from error messages. So here is the whole model in plain language. The later pages in this section go deep on the ones that reward it.

1. Identity — who is acting

Every actor in TOVIO — you, a teammate, an AI agent, a CI runner — is a cryptographic identity: a keypair that TOVIO generates for you. For a solo project this is invisible. It is created silently at tovio init and you never think about it. It becomes visible only when you collaborate or grant an agent access. There is no "anonymous" actor: every protected read is attributable to an identity.

Mental model

Your signing identity — like an SSH key that TOVIO manages for you, rather than one you generate, copy, and paste into a settings page.

2. Change — a unit of work

A change is what you are working on right now: one task. It has a stable name — its Change ID, for example chg:xkqm7y — that TOVIO's history-rewriting commands leave unchanged. You don't create changes with ceremony; you just start editing, and TOVIO tracks your working copy as the current change automatically. There is no staging area. tovio add survives only as a Git-compatibility no-op: the paths you pass are ignored, because there is nothing to stage.

When you amend, rebase, absorb, or split a change, the Change ID stays the same. You, your teammates, CI, and your agents can always point at "change xkqm7y" across every one of those rewrites. This single idea is what removes rebase-and-force-push anxiety.

Mental model

A change is a Git branch and its commits combined into one named unit of work, with a permanent name that survives history edits.

The change is the concept Git users have to unlearn the most, so it has its own page.

3. Commit — a saved snapshot

A commit is an immutable snapshot of your files plus metadata. It has a content hash — its Commit ID — that does change when the content changes. A change points at its current commit; rewriting history makes new commits but keeps the change's identity.

Mental model

A Git commit. Same idea — TOVIO just also stamps it with a Change ID, so the snapshot and the unit of work it belongs to are two separate, separately-named things.

4. Conflict — a question the repo holds for you

When two changes can't be merged automatically, TOVIO stores the conflict as an object and keeps going. The merge completes. Your in-flight work is not blocked, your teammates keep working, and the conflict sits as an open question until someone resolves it — and when they do, the resolution propagates everywhere that same conflict appears.

Mental model

Think of a conflict like a type error, not a runtime crash. It lets you keep editing, saving, and committing other files — it is visible and tracked — but it is not "clean" until resolved.

"Non-blocking" has a precise scope and real limits, which the conflicts page lays out carefully.

5. Policy — who may read a path

For most files there is no policy — anyone with repository access can read them, and you never think about encryption. A policy is an access rule you attach to a path, for example config/production/**. Once a path has a policy, files there are automatically encrypted so that only identities who satisfy the policy can read them — even if they clone the whole repo. You don't manage keys by hand; you declare who should be able to read, and TOVIO does the rest.

Mental model

A .gitignored secret file plus an external secrets manager — except the file actually lives in the repo, and the protection is enforced by mathematics, not by a server you have to trust.

The permissions page explains the crypto tiers and the Key Authority.

6. Capability — what an agent is allowed to do

When you point an AI agent — an editor integration or a custom bot — at your repo, you give it a capability: a signed, expiring token that bounds paths, operations, delegation, and protected-context clearance. Without both an authorized capability chain and usable recipient key material, TOVIO does not decrypt protected context for that agent identity. A user, tool, runner, or model endpoint can still receive plaintext that an authorized principal explicitly discloses outside that boundary.

Agent-authored work can carry signed, bounded provenance such as the agent identity, task/run context, tool-manifest binding, and declared model metadata. The exact fields depend on the operation and do not imply that every prompt or external model interaction is captured.

Mental model

A fine-grained personal access token — scoped to paths, tied to an agent identity, and short-lived.

The agents page goes deeper on scoping and provenance.

7. Forge — where people share

A forge is the optional server where teams sync and collaborate: review, audit, locks, and agent coordination. It can run inside your own perimeter, or as hosted TOVIO Cloud — a service that is not yet generally available. The Forge enforces hosted write, administration, and collaboration gates and controls the availability of the service it runs. Its object store receives ciphertext for protected payloads without receiving recipient private keys or unwrapped data keys merely to host them; public content, paths, policy and collaboration metadata, and explicitly authorized disclosures have different boundaries.

Mental model

A collaboration peer whose protected object store is ciphertext-oriented, not a server outside every trust boundary.

The Forge page draws the exact trust boundary.

What you do not have to think about

A core design rule: advanced power stays invisible until you reach for it.

  • If you never write a policy, you will never see encryption, keys, or a Key Authority.
  • If you never register an agent, capability tokens don't exist for you.
  • tovio help shows only the everyday tier — a governed list, seventeen commands today — not the full surface. Team and advanced features live behind tovio help --team and tovio help --advanced.

You can use TOVIO as a cleaner Git for a long time before you ever touch its differentiators. Four of these seven concepts — identity, change, commit, conflict — are the everyday core. The other three — policy, capability, forge — appear exactly when a real need for them appears, and not before.

Where to go next

  • Already know Git? Coming from Git maps every concept and names the mental flips.
  • Want the everyday workflow? Get started walks the loop hands-on.
  • Want the why behind a decision? Each page links the relevant Architecture Decision Records.

Last reviewed September 9, 2026

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