Collaborate with a team¶

In this tutorial you will see the shape of teamwork in TOVIO: clone a repository from a Forge, do some work, sync it (push and pull in one), and propose a change for review. If you know the GitHub flow, this will feel familiar — with a few TOVIO twists that remove the friction Git puts in your way.

Implemented; release evidence remains open

Networked sync — tovio clone, sync, push, and pull over TLS — is built and runs today. The commercial Forge (proposals, review, lane protection, ACL, locks) is built and hermetically tested; production binaries passed the distinct-Docker-host exercise under a real operator CA. The public release, broader HA/load, hosted-parity, and external evidence gates remain open, so this is not a general-availability claim. The local building blocks — changes, lanes, landing, conflicts — are runnable now (see the solo tutorial).

The one thing to understand first¶

A Forge is the optional server where teams meet to sync and review. Two things make it unlike a Git host:

Protected payloads are encrypted in storage. The Forge stores and serves ciphertext for protected files; compromising that object/API view alone does not yield their plaintext. Public content, metadata, authorized endpoints, and the Tier-1 Key Authority retain separate trust boundaries.
Divergence reconciles on the lane. When two authorized replicas move the same unprotected lane offline and then sync, TOVIO joins the two tips into a two-parent merge-or-conflict commit on that lane — both tips are parents, so nothing is stranded off-lane and no force-push is ever needed. (An HLC-keyed CRDT register propagates the resulting pointer between replicas; it's the mechanism, not the resolution.) Sync can still refuse an invalid signature, insufficient path/capability scope, protected-ref or lock violation, missing object closure, quota denial, stale state, or unavailable transport.

The full model is in Core concepts; here's the workflow.

Step 1 — Clone from a Forge¶

tovio clone takes the relay address, the repository id — the blake3: address the Forge prints, not a human name — and the directory to create. Point it at the Forge's certificate the first time:

tovio clone forge.example.dev:7743 \
  blake3:0f5a2c7d91e34b86ac5f1d20e8b47c93a6d0f81b5e2947c3d6a08f14b7e2c5d9 \
  payments-service --cert forge.der
cd payments-service

✓ Cloned 1284 objects from forge.example.dev:7743 into /home/you/payments-service
  repository blake3:0f5a2c7d91e34b86ac5f1d20e8b47c93a6d0f81b5e2947c3d6a08f14b7e2c5d9
  working copy materialized at lane `main`
  server identity did:key:3e91c47a08b52d6f1a94e703cb85df26107a4b98e5c31d6f2098a7b4e6c150d3 (pin this for next time)
  → Next: `cd payments-service`, then `tovio log` to browse history or `tovio status` to see the current change

The clone stores that relay, repository id and certificate as this repo's origin, which is why every later tovio sync needs no arguments. A hosted https:// Forge is the other shape — it drops the --cert and is trusted through public PKI instead — but the proposal and review commands in Steps 4 and 5 speak the native, cert-pinned form, so this tutorial stays on one relay throughout.

Permission-aware, and as partial as you ask for

A clone is complete by default. Protected objects arrive as ciphertext and decrypt on access only if your identity satisfies their policy — that part is never optional. What is optional is how much you take: --sparse "src/**" limits the clone to a path cone, --blobless and --blob-limit <bytes> omit file content that backfills lazily on read, and --depth <n> takes a shallow slice of history.

Step 2 — Do some work¶

Same loop you already know. Make a lane for the work, edit, commit:

tovio lane my-lane
tovio switch my-lane
echo "fn refund() {}" > src/refund.rs
tovio commit -m "Add refund handler"

✓ committed  chg:ac5fke84fkywmhr23h22bwc1j8  blake3:7c5cf7e221…
  184 file(s) · new change chg:yt6sbxzwz9tthp7j17by51k58w · undo with `tovio undo`
  → Next: `tovio land` to merge onto main, or `tovio log` to review

That 184 is the whole tracked snapshot, not the size of your diff — you changed one file, and TOVIO recorded the complete tree it now points at. tovio diff is what shows you what changed.

Step 3 — Sync: push and pull, in one¶

In Git you commonly run separate pull and push steps. In TOVIO, tovio sync performs both directions at once. A divergent lane never requires a force-push — sync reconciles it on the lane into a merge-or-conflict commit; all normal authorization, integrity, policy, object-closure, quota, lock, and transport gates still apply.

tovio sync

✓ Synced with forge.example.dev:7743 (received 4 object(s), sent 1; 2 ref(s) merged)

If a teammate moved the same lane while you were offline, sync adds a reconciliation line — and it's a good thing, not an error:

✓ Synced with forge.example.dev:7743 (received 9 object(s), sent 1; 1 ref(s) merged)
  ✓ reconciled divergent lane `main` on-lane (clean merge, blake3:7c2e91b0f4a3d5c8e21b6047fa9d3c15e08b7241d6f0a95c3e7b18d24af60c93)

Your lane and your teammate's diverged offline, and TOVIO joined them into one merge commit on the lane. No force-push, and nothing stranded.

Coming from Git?

Muscle memory is welcome. tovio push and tovio pull are real commands, not aliases — give each a relay and a repository id (tovio push <relay> <repo> --cert <file>, or an https:// Forge with no cert) and it transfers objects and refs. Typed bare, out of Git habit, they transfer nothing and print the explicit form plus a note that tovio sync is the native verb that does both at once.

When a teammate's work isn't ready¶

TOVIO won't drop someone else's broken state into your tree. If you try to build on a teammate's change that still has an unresolved conflict, sync tells you — rather than silently dumping conflict markers into your working copy and breaking your build:

✗ Cannot pull chg:002 as a dependency: 1 unresolved conflict(s)

  Change chg:002 has 1 unresolved conflict object(s); materializing it into the working tree as a dependency you build on top of would break the build. The objects still downloaded (REQ-SYNC-002) — only the materialization is refused.
    ~ src/integrations/auth/oauth.ts

  Notify the author:
    tovio change notify chg:002
  Build against the last-known-clean version:
    tovio materialize --isolate
  List the conflicted paths:
    tovio status --conflicts
  Read one side of a conflicted path:
    tovio cat <path> --side ours

  [TVO-CONFLICT-004]  https://tovio.dev/errors/TVO-CONFLICT-004

Notice what did not happen: the objects downloaded fine, and only the materialization was refused. You choose: record a notify-intent with tovio change notify chg:002 and wait for Bob to resolve, or build against the last-known-clean version — tovio materialize --isolate locally, or tovio sync --isolate when the fix has to come over the network. Your own in-flight conflicts never block you; this gate is only about not inheriting a teammate's broken build.

Step 4 — Propose a change for review¶

The pull-request equivalent. Push the change, then open it for review on the Forge:

tovio change propose chg:ac5fke84fkywmhr23h22bwc1j8 \
  --remote forge.example.dev:7743 --cert .tovio/origin-cert.der --target main

✓ Proposed chg:ac5fke84fkywmhr23h22bwc1j8 to main on the Forge (proposal prop:003 is now open).

A proposal (prop:…) is a first-class Forge object linking your change to its target lane and the review decisions cast against it. Push the change to the Forge first, so its commits are already there; who may review is the repository's policy to decide, not a flag on this command.

Both of these commands pin the Forge's certificate. --cert defaults to .tovio/relay-cert.der, which is what tovio serve writes on the serving machine — a clone stores its pinned origin certificate as .tovio/origin-cert.der instead, so name it explicitly as above.

Step 5 — Review (the other side)¶

Your reviewer, Alice, reads the diff and decides. tovio review is addressed by change id, not proposal id — the proposal is only where the decision gets recorded:

# A local render of the diff, redacted where Alice can't read:
tovio review chg:ac5fke84fkywmhr23h22bwc1j8

# The decision, submitted to the Forge:
tovio review chg:ac5fke84fkywmhr23h22bwc1j8 --approve \
  --proposal prop:003 --remote forge.example.dev:7743 --cert .tovio/origin-cert.der

✓ approved chg:ac5fke84fkywmhr23h22bwc1j8 on the Forge (proposal prop:003 is now approved).
  advisory coverage submitted: 3 covered, 0 not accessible to you.

Without a decision flag the command is a purely local render. The reviewer is Alice's signing identity, never a field she fills in. On a lane whose protection requires review, approval is a pre-land gate — the Forge refuses to advance the lane until the proposal is approved, and --request-changes keeps it blocked until addressed.

Step 6 — Land it¶

With the proposal approved and the change conflict-free, land it onto main:

tovio land my-lane --into main

✓ landed `my-lane` into `main`  blake3:8476f19d51…
  1 file(s) merged · same Change IDs — your work kept its identity · undo with `tovio undo`

The two gates sit in different places, and the review requirement arms both. tovio land enforces the conflict-free rule locally: on a lane protected with --require-review, a land that would leave unresolved conflicts is refused outright (TVO-CONFLICT-003). Protect a lane without one and that refusal never fires — the same land materializes a conflict commit and stores it as data. The approval gate lives on the Forge, which refuses the ref update when the proposal is not approved and re-certifies the incoming commit as conflict-free on the way in — so neither gate is sidestepped by landing locally and pushing.

What you learned¶

A Forge is where teams meet to sync and review. Its object store receives ciphertext for protected payloads, while public content, metadata, operations, and disclosure endpoints remain part of the operator trust boundary.
tovio sync does push and pull in one, and a divergent lane reconciles on the lane into a two-parent merge-or-conflict commit — no non-fast-forward force-push workflow.
TOVIO won't materialize a teammate's unresolved-conflict change into your tree and break your build; you wait, or build at last-known-clean with tovio materialize --isolate / tovio sync --isolate.
tovio change propose + tovio review is the PR-equivalent flow, and approval gates the land onto a protected lane.

Next¶

Teams aren't only humans. The same authorization model bounds AI agents — with scoped tokens, secret clearance they can't bypass, and provenance on every commit.

Give an agent access

Last reviewed September 9, 2026

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