Cookbook¶
Short, copy-paste recipes for common tasks. Each one is a goal, the steps to reach it, and a note on what it gets you. For deeper walkthroughs, each recipe links to the guide that covers it in full.
Current capability boundary
Encryption, agents, network sync, the bidirectional Git bridge, and the single-node Forge are implemented. What remains is productization rather than the feature: the release packaging is built but unpublished, and production multi-host verification is still open. Where a recipe reaches a narrower boundary it says so inline. See the roadmap.
Protect a .env so it stays encrypted in the repo¶
Goal: commit config/prod.env so it's readable by your team but ciphertext to anyone without
clearance --- even if they clone the whole repo.
# 1. Write a policy: only identities with clearance=prod may read this path.
tovio policy set "config/prod.env" --read "clearance=prod"
# 2. Commit the file. It's encrypted at snapshot time, before it lands in a tree.
tovio commit -m "Add production env, policy-protected"
# 3. Prove it. Confirm what the policy requires and whether you satisfy it.
tovio access check config/prod.env
What this gets you. The file is encrypted under a per-object key that's wrapped only for
identities with clearance=prod. Plaintext never enters a tracked tree. Someone can clone the entire
repository and still not read prod.env --- the math enforces it, not a server.
Protect a whole directory
Use a glob to cover everything under a path: tovio policy set "config/prod/**" --read "clearance=prod".
To revoke someone later, remove their attribute; TOVIO rotates the data key and re-wraps it for the remaining identities so newly committed content is unreadable to them. Full walkthrough: permissions guides.
Give Cursor (or Claude Code) scoped, audited access¶
Goal: let an AI coding agent work on your clear code for one session, with no access to your protected paths.
# 1. Issue a capability token. The model and task are required — they are what
# the provenance on every resulting commit records. --expires-in is in hours.
tovio agent new cursor --model "anthropic:claude-opus-4-8" \
--task "refactor the checkout module" --expires-in 8
# 2. Hand the token to the agent's MCP client. The server validates it on every tool call.
tovio agent token <token-id>
tovio mcp serve --token <token-id>
What this gets you. A signed token whose defaults are the safe ones: broad access to clear code,
excluded from every policy-protected path, no escalation, and a required expiry. Because the token
carries no secret clearance, the agent is never wrapped a key for a protected file --- even one inside
the tree it is working in. Any read or write outside its scope fails on the path check before
decryption is even attempted (TVO-TOKEN-001), and every operation the agent
performs is recorded with provenance (model, task, who authorized it).
Tokens are least-privilege by default
Take the shortest expiry that is practical, and grant delegation (--can-delegate) only when the
agent actually needs it --- it is off by default. A sub-token an agent delegates can only ever be
equal-or-narrower than the one you issued.
When the session ends, the token expires on its own --- no cleanup step. Renew proactively with
tovio agent renew <token-id> if the work runs long. Full details:
AI agents section.
Migrate a Git repo into TOVIO¶
Goal: bring an existing Git project into TOVIO without losing history.
# 1. Import targets a FRESH TOVIO repository, so make one first.
mkdir my-project && cd my-project
tovio init
# 2. Import the Git repo. History is walked; each commit gets a TOVIO change ID.
tovio git import ../my-old-repo
# 3. Look at the imported history.
tovio log
What this gets you. A native TOVIO repository. Every Git commit becomes a change with a stable
chg: ID, and the git-hash → commit → change-id map is written to
.tovio/git-import/commits.tsv so the original hashes stay recoverable. Your .gitignore files are
rebased onto the repository root as a .tovioignore (--no-ignore-translate opts out). Import is
one-way --- it reads Git, it doesn't rewrite it.
The target must be empty
Import refuses a repository that already has a lane, so imported history can never tangle with
hand-made commits (TVO-MIG-002). To retry a partial import, start from a
clean tovio init.
Keeping a foot in both worlds
One-way import, one-shot export, and tovio git bridge <remote> --bidirectional work today. The
bridge exchanges disjoint Git/TOVIO namespaces without force-pushing either side.
Full walkthrough: migration guides.
Set up a monorepo with per-area permissions¶
Goal: one repository, several teams, each able to read only its own area's secrets.
# Each area gets its own read policy.
tovio policy set "services/payments/**" --read "team=payments"
tovio policy set "services/identity/**" --read "team=identity"
# Commit normally --- each path is encrypted under its own policy at snapshot time.
tovio commit -m "Scaffold payments and identity services"
To keep main from advancing on a non-conflict-free change, list it under protected_branches in
the policy manifest; tovio land then refuses to advance a protected lane to a change that isn't
clean.
What this gets you. A single repo where everyone shares the code but each team's protected paths are ciphertext to the others. Permissions are per-path, so there's no need to split the monorepo into many repos just to separate secrets. Sparse, capability-scoped sync is implemented and lets a developer materialize only the paths they're authorized for and actually need --- so a big monorepo doesn't mean a big checkout.
Permissions are the shard boundary
TOVIO partitions storage by path prefix on the same boundaries as permissions. Structuring a monorepo by team area lines up cleanly with both how access is granted and how the Forge scales.
Recover from a mistake¶
Goal: undo an operation that went wrong --- a bad rebase, a wrong commit, a deleted lane.
# Reverse the last operation. It tells you what it undid.
tovio undo
# Changed your mind? Put it back.
tovio redo
What this gets you. TOVIO keeps a local operation log and tovio undo reverses supported retained
mutations, not just commits. This is local state recovery, not a recall mechanism: it cannot erase
effects already observed by peers or external systems, and authenticated obliteration remains permanent.
See what's protected and who's active¶
Goal: at a glance, know which files are encrypted and whether an agent is running.
What this gets you. tovio status aligns protection indicators (a lock glyph on policy-protected
paths), active agent sessions, and conflict counts into one scannable view --- so trust state is
visible, not buried. Full reference: CLI reference.
Last reviewed September 9, 2026
Suggest an improvement to this page Not for security reports — see disclosure