Skip to content

Promote a repository to a higher mode

tovio init offers three Key Authority (KA) modes — simple (Solo), team, and agentic — picked by answering a single question ("who will work on this?"), or by passing --mode. That choice is not a one-way door: a Solo notebook can become a Team repository the day a second developer joins, with one command and without touching a byte of your existing history.

A fourth mode, Enterprise (CP-ABE), exists behind a separately licensed release boundary. It is not offered by tovio init, and the promotion flow into it is not generally available.

This page shows exactly what a promotion is, what it changes on disk, what it does not change, and how to actually run one for a shared team repository.

What is built, and what is not

Solo → Team is built and shipping: tovio identity init provisions the identity and Key Authority for an existing Simple repository, and the Phase-1 permission layer (policy, access, audit) is done, so everything downstream of it can be exercised in an authorized source checkout.

There is no separate Team → Agentic promotion command, and none is needed — tovio agent new issues scoped capability tokens in a Team repository as it stands. The agentic mode is an init choice, not a gate you have to cross later.

Tier-2 CP-ABE has passed its enterprise KA conformance/internal-review gate but remains private and release-gated, and there is no Enterprise promotion command. Its abe recipient kind does not require re-encrypting public history; threshold/KMS/HSM authority is a separate, later profile and is not a prerequisite for CP-ABE.

The modes at a glance

The mode determines what a Key Authority does for this repository. It does not change the storage format, the wire protocol, or how commits work.

Mode KA form What it enables Setup cost
Simple (Solo) None No identity, no policies, no collaborators — plain content-addressed version control. Zero. Nothing to set up.
Team Authorization oracle Policies on paths, per-recipient wrapped DEKs, access grant/revoke, the audit log. One-time: provision the identity/KA, enroll teammates' public keys.
Agentic Oracle + token issuer Everything in Team, framed around agent capability tokens. tovio agent new also works in a Team repo. Same as Team.
Enterprise CP-ABE KA; later threshold/KMS profile Cryptographic policy-at-decrypt enforcement. k-of-n or HSM/KMS authority remains a later option, not a prerequisite for CP-ABE. Highest; private and release-gated, and not an init choice.

Full conceptual treatment: Permissions.

What "promotion" actually is

A promotion is additive. It does not rewrite history, does not re-encrypt existing objects, and does not change any object address:

  • It provisions a cryptographic identity and Key Authority for the repository (Solo → Team).
  • It gives you an identity.pub to share, so teammates' public keys can be enrolled into the identity-to-public-key registry and future policies can wrap DEKs for them.
  • It turns on a group of commands that a Simple repo has no identity to run (policy …, access grant, access revoke, audit …, key …, agent …).

Because clear objects are never encrypted, promoting does not touch your existing public history — tovio identity init says so in its own output. Any policy-protected files you created before promotion keep their existing recipient wraps; new grants after promotion add wraps for the newly enrolled identities.

Promotion flow

flowchart LR
    S["Solo<br/>(no identity, no KA)"] -->|"tovio identity init"| T["Team<br/>(oracle KA)"]
    T -->|"tovio agent new<br/>(no promotion needed)"| A["Agent tokens<br/>(oracle + token issuer)"]
    T -.->|"no command today"| E["Enterprise<br/>(CP-ABE KA;<br/>private, release-gated)"]
    classDef future fill:#eee,stroke:#999,color:#666
    class E future

Promotion is forward-only: there is no command that takes a Team repository back to Simple, and none is planned — a downgrade would have to revoke every issued capability token and re-verify every claim signed under the KA. If you truly need to "downgrade," the answer is to start a fresh repo at the lower mode and import history.

For the full workflow set, see Permissions & review workflows.

What a Solo → Team promotion actually does

This is the promotion most projects will run, so it is worth walking through in detail. Assume you have a Solo repo you started for yourself and a teammate is joining.

  1. Provision the KA. TOVIO creates the repository's Key Authority as an authorization oracle: an identity-to-public-key registry plus signed attribute claims. The KA never sees plaintext or content keys.
  2. Enroll public keys. You add your teammates' identity public keys to the registry. Their private keys never leave their machines.
  3. Turn on the permission commands. tovio policy, tovio access grant/revoke, and tovio audit become available.
  4. Public history is untouched. Every clear commit before the promotion is still a clear commit after — content addresses do not change, and the wire protocol version does not change.
  5. First policy is a normal operation. Running your first tovio policy set after promotion is what actually starts encrypting the paths it matches, on the next commit (see Write a policy).

The KA can live on a Forge or on your own machine

In a small team, the KA can literally be one developer's laptop acting as the oracle. In a bigger team it is typically hosted by the Forge. Either way the KA is never the thing that decrypts your files — it only decides whose wrapped DEK copies are included at grant time.

Promoting an existing Solo repo to Team

The command is tovio identity init. It takes no arguments — enrollment is a separate, later step, because a teammate has to hand you their public identity first.

$ tovio identity init
✓ Upgraded to Team mode — identity did:key:dae6be2ae7a2855ff5e8620732a31ff32e192778eace4202e7482bf93ab1adc9
  Existing public history stays clear (not re-encrypted).
  Protect paths with `tovio policy set <glob> --read <attr>` and enroll teammates
  with `tovio access grant --identity <file>`.

  ┌─ RECOVERY KEY — save this before your first protected commit ─────────────
  │  Recovery phrase:  a1b2c3…
  │
  │  WARNING: if you lose BOTH your identity key AND this recovery phrase, your
  │  protected files are UNRECOVERABLE. An owner-only fallback remains until
  │  you type `saved`; exact acknowledgement removes that fallback.
  └──────────────────────────────────────────────────────────────────────────
  Type `saved` once you have escrowed the phrase (or press Enter to skip):

What just happened: TOVIO generated this repository's Ed25519 signing key and X25519 key-agreement key, sealed the secret into your OS keychain, made you the repository owner and its initial KA, and generated a recovery phrase. Nothing in objects/ was re-encoded.

Escrow that phrase before you answer the prompt. Typing saved deletes the owner-only fallback file; pressing Enter leaves it in place and tells you where it is. Run this unattended (--json, --quiet, or with no TTY) and there is no prompt at all — the phrase goes straight to .tovio/tovio-recovery-key.txt for you to move and delete. Either way, see recover a lost key first; this is the step that decides whether a lost key is recoverable.

Verify, then enroll:

$ tovio identity show
Identity: did:key:dae6be2ae7a2855f…
  key-agreement key (pk_kx):  0533099c724fa75e…
  secret sealed in keychain:  yes
  share .tovio/identity.pub so a teammate can `tovio access grant --identity <file>`.

$ tovio policy list
(no policies yet)

$ tovio access list
No enrolled recipients. The repository owner can always read its own protected files.

Alice and Bob each send you their .tovio/identity.pub, and you enroll them one at a time with tovio access grant — confirming the pairing code it prints, out of band, each time.

You are now ready to write your first policy.

Agentic: there is nothing to promote

Agentic mode is a strict superset of Team mode: the same KA issues and validates scoped capability tokens. In the shipping build that superset is already available to a Team repository — a Team repo's identity is the token issuer, so tovio agent new mints a token there without any mode change:

$ tovio agent new reviewer --model "anthropic:claude-opus-4-8" --task "review the diff" --expires-in 1
token cap_238545309b986bfda27a30da57bafafc
  agent:       did:tovio:agent/reviewer
  authorized:  did:key:559ebdc73461a508… (human)
  scope:       **  (excluding 1 protected path(s))
  excluded:    config/production/**
  branches:    agent/reviewer/**
  window:      [2026-09-09 10:57:49 -04:00, 2026-09-09 11:57:49 -04:00)  clearance=false

agentic is therefore an init-time framing choice, not a capability gate you cross later. Note the safe defaults it starts from: broad access to clear code, excluded from every policy-protected path, no escalation, and a required expiry (24 hours unless you pass --expires-in). See Agents & capabilities and Capability tokens for the token contract.

What an Enterprise promotion will do

Enterprise mode is Tier 2 (CP-ABE). There is no promotion command today; when one lands, it will not re-encrypt existing content. What changes is the enforcement point:

  • Policies may express CP-ABE attribute expressions that are enforced cryptographically at decrypt time, closing the residual Team-tier trust in the KA (see Permissions).
  • A threshold (k-of-n Shamir) or KMS/HSM-backed KA root — so that grants and enrollments require a quorum or an HSM operation rather than one owner key — is a separate, later profile. It is not a prerequisite for CP-ABE, and it is not part of the Tier-2 release that passed the conformance gate.

Because the envelope is ABE-forward from day one, existing Tier 1 objects remain readable by their existing recipients after the promotion; new policies written under Enterprise mode can add CP-ABE recipients to the same envelope.

Before and after you promote

tovio identity init is a no-op on a repository that already has one — it reports the existing DID and stops, "regenerating would orphan content sealed to the current key" — and there is little else it can check, because a Simple repo has no protected content and no recipients to lock out. The work that protects you is on either side of it:

  • Escrow the recovery phrase. The promotion generates one and shows it to you once. Get it somewhere safe before your first protected commit — after that, losing your key without it is data loss. See Recover a lost key.
  • Commit in-flight work first. Any change that would touch a soon-to-be-protected path should be committed before you set the policy, so the transition to ciphertext is a clean, reviewable step rather than a surprise inside a large snapshot.
  • You become the repository owner. The identity identity init creates is the pinned owner root, and only that root can write an authoritative policy manifest (TVO-PERM-007). Promote from the machine that will hold that key.

What a promotion does not do

Being precise about the negatives is important, because promotion is often imagined as more disruptive than it is:

  • It does not re-encrypt existing content. Old clear commits stay clear, and old Tier 1 policy objects keep their existing recipient wraps.
  • It does not change any object's address. Content addressing is stable across the promotion.
  • It does not change the wire protocol version. Existing clones continue to sync without upgrading.
  • It does not grant read access to anyone new. Enrollment only adds a public key to the registry; a teammate still cannot read a protected file until an authorized identity runs tovio access grant for that policy.
  • It does not issue any capability tokens. Only tovio agent new does that.

Common questions

Can I promote a repository that already has policy-protected files?

A Simple repository has no cryptographic identity, so it has no policies and no protected files to worry about — promotion is what gives it the ability to have them. If you are asking about existing clear history, that stays clear and unchanged; you then write policies and grant on the paths you want protected from the next commit onward.

Do collaborators have to re-clone after promotion?

No. The new identity and enrollment records sync like any other object on the next tovio sync. Your teammates' existing clones pick them up.

Can I promote temporarily — say, for a security review?

Not really. Promotion is forward-only by design (see the flow diagram above). If you need a scoped, time-boxed elevation for an auditor or an agent, that's what capability tokens are for.

What happens if the owner identity is lost after promotion?

The same recovery flow that protects any Team identity applies to the owner: move the recovery phrase off the machine before the first protected commit, and tovio key recover can install a fresh identity later. Note that a recovery drops teammate and device recipients whose claims the lost key signed, so they have to be re-granted. See Recover a lost key.

Where to go next

Last reviewed September 9, 2026

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