Give an agent access¶

In this tutorial you will do something no other version control system lets you do: hand an AI coding agent a scoped, expiring capability token, point its tooling at your repo through the MCP server, and watch every commit it makes carry provenance — which model, which task, which human authorized it. And the agent will be unable to read your secrets, not because a rule forbids it, but because its key cannot decrypt them.

This is TOVIO treating agents as first-class, bounded participants.

Phase 2 runs across the CLI and MCP edge

The agent control plane — capability tokens, secret_clearance enforced at read and seal, commit --token, the agent commands, provenance, Node bindings/SDK, and MCP tools — is built and runs today from the workspace. The npm packages are unpublished, so Step 3 builds the MCP server out of the workspace rather than installing a released one. The permission model this builds on is introduced in Protect a secret.

The idea in one minute¶

A capability token is a signed, expiring certificate that says exactly what an agent may do:

a path scope — which paths it may touch (default **, excluding every policy-protected path) and a branch scope, which is always the agent's own agent/<name>/** namespace;
a secret clearance flag — whether it may read protected files (default: false);
allowed and denied operations — the default allows read, commit, amend, branch:create, relay:fetch, relay:push and conflict:resolve, and explicitly denies obliterate, policy:modify, tag:create, tag:force and sub-token:issue. Key management is not on the list at all;
an expiry — --expires-in <hours>, defaulting to 24, and a token has to be renewed rather than extended.

The crucial TOVIO read guarantee: an agent with secret_clearance: false is not handed the key to a protected object, regardless of its path scope. The TOVIO surface therefore does not disclose that plaintext. This token does not sandbox unrelated tools or retract context supplied outside TOVIO.

Step 1 — Enable agents¶

Agent registration lives in Agentic Mode. Initialize (or re-init) the repo so the agent commands are surfaced:

mkdir billing-service && cd billing-service
tovio init --mode agentic

✓ Initialized empty TOVIO repository in /path/to/billing-service/.tovio
  On branch main · current change chg:f4m3gm4rept7q5xf9jecb8vdkg · mode: agentic
  Identity did:key:f0dcde0fb55fa719351b130d0c89594e20316e24244e73ecc99dfdf65683c0ff generated and sealed in your OS keychain.
  Protect paths with `tovio policy set …` — matching files encrypt on the next commit.
  → Next: edit files, then `tovio commit -m "…"`
  Recovery phrase written to /path/to/billing-service/.tovio/tovio-recovery-key.txt (owner-only, kept out of commits) — move it somewhere
  safe (a password manager), then delete it. Losing BOTH your key and this phrase is unrecoverable.

Step 2 — Issue a scoped token¶

Name the agent, say which model runs it and what it is here to do, and give it two hours:

tovio agent new claude-code \
  --model "anthropic:claude-opus-4-8" \
  --task "Add input validation to the invoice parser" \
  --expires-in 2

token cap_3b6d17f7f0136f62bd32825185a349a9
  agent:       did:tovio:agent/claude-code
  model:       anthropic:claude-opus-4-8
  authorized:  did:key:f0dcde0fb55fa719351b130d0c89594e20316e24244e73ecc99dfdf65683c0ff (human)
  scope:       **  (excluding 0 protected path(s))
  branches:    agent/claude-code/**
  window:      [2026-09-09 11:16:17 -04:00, 2026-09-09 13:16:17 -04:00)  clearance=false
  object:      89c3911167ec1cc02778fe5eeb9407f6b2ca54e58ccb81ced5b69bc8d0ded3f3

That's the whole onboarding — one command with safe defaults. Notice what you didn't have to do: you didn't grant secret clearance, you didn't have to remember to deny dangerous operations, and you didn't have to carve out the protected paths — the scope excludes them for you. The safe defaults are the point.

Read the branches: line carefully, because it is the boundary you will meet first: this token may only commit onto agent/claude-code/**. Its own lane is where an agent works; getting that work onto main is a human's tovio agent promote.

The dials you do have

# Default window — 24 hours
tovio agent new cursor --model "anthropic:claude-opus-4-8" --task "Triage flaky tests"

# Shorter window, in hours
tovio agent new cursor --model "anthropic:claude-opus-4-8" --task "Triage flaky tests" --expires-in 2

# Let this agent mint narrower sub-tokens of its own (off by default)
tovio agent new orchestrator --model "anthropic:claude-opus-4-8" --task "Fan out refactor" --can-delegate

Narrower path scopes come from delegation — an agent holding --can-delegate issues sub-tokens that can only ever shrink its own scope. tovio agent new itself has no --scope flag.

Step 3 — Hand the token to the agent and run the MCP server¶

TOVIO speaks the Model Context Protocol, so agent tooling is native. The server is the tovio-mcp-server package; build it out of the workspace, then run it against the repository with the token:

pnpm --filter tovio-mcp-server build
TOVIO_REPO=/absolute/path/to/repo TOVIO_TOKEN=cap_3b6d17f7f0136f62bd32825185a349a9 pnpm --filter tovio-mcp-server start

tovio-mcp-server: ready — agent did:tovio:agent/claude-code, 1 scope glob(s), secret_clearance=false

tovio mcp serve is the launcher, not the server

Once tovio-mcp-server is on your PATH, tovio mcp serve --token cap_… is the friendlier way in: it resolves the repository, passes TOVIO_REPO/TOVIO_TOKEN, and execs that binary for you — over stdio by default, or streamable HTTP with --port 7744 / --transport http (bound to 127.0.0.1 unless you say otherwise). Run it without the binary installed and it fails with TVO-MCP-002, whose remedy is exactly the build step above. Set TOVIO_MCP_SERVER_BIN to point it at a build that is not on your PATH.

The HTTP transport is bearer-authenticated — and it terminates no TLS

The streamable-HTTP edge is never unauthenticated: every request must carry Authorization: Bearer …. Supply the secret in TOVIO_MCP_BEARER; leave it unset and the listener mints a 256-bit one for that run and prints it on the readiness line, because a loopback bind identifies the host, not the process behind it — the check is not dropped there either. A non-loopback --bind refuses to start at all without TOVIO_MCP_BEARER (127.0.0.1, localhost and ::1 are the loopback set). What the server does not do is terminate TLS: the endpoint it announces is plain http://. Put a TLS terminator in front of any bind that is reachable off the host — nothing in TOVIO checks that you did. Over stdio none of this applies; the pipe is the boundary.

tovio agent token cap_3b6d17f7f0136f62bd32825185a349a9 prints the token in the machine form a client that wants the bytes rather than the id can consume.

Every tool call the agent makes is validated against that token. The MCP server never exposes obliterate, policy:modify, or key management to an agent connection — those simply aren't on the menu.

Step 4 — Watch the agent work, bounded¶

The agent edits and commits within its scope, exactly like a teammate — but two boundaries hold automatically.

It cannot touch what's out of scope. A commit aimed outside the token's branch or path scope is refused before anything is sealed — here, an agent trying to commit straight onto main:

✗ Agent token is not scoped to branch `main`

  An agent may act only within its token's path_scope (minus denied_path_scope) and branch_scope; this operation targeted something outside that scope, so it is rejected before any policy or envelope is consulted (§7 step 2).

  Re-issue the token with a wider scope (`tovio agent new`), or act only on in-scope paths

  [TVO-TOKEN-001]  https://tovio.dev/errors/TVO-TOKEN-001

Take the remedy line with a pinch of salt on this particular failure: tovio agent new has no --scope flag to widen, and the violation here is the branch, not a path. The real answer is the one the token's branches: line already gave you — the agent works on its own lane:

tovio lane agent/claude-code/validation
tovio switch agent/claude-code/validation
# ...the agent edits and commits here, under its token...

Getting that lane onto main stays a human decision: tovio agent promote lands an agent's branch onto a target and tears the branch down.

It cannot read what it has no clearance for. Even if a protected path were in scope, an agent with secret_clearance: false is never handed the decryption key. The protection is the same cryptography from Protect a secret — a rule isn't saying "no," the math simply won't decrypt.

Step 5 — See the provenance¶

Every commit an agent authors records structured provenance. Look at the agent's history:

tovio log --entity agent

@ chg:tef7sq6pjmefpa5spwt4ez4jhr  (agent/claude-code/validation)  🤖
  Add input validation to invoice parser
  you · just now · blake3:93516cef17…
  agent anthropic:claude-opus-4-8 · task task_05eecaf78336da14 · authorized by did:key:f0dcde0fb55fa719351b130d0c89594e20316e24244e73ecc99dfdf65683c0ff
  🖥 signed by device did:key:f0dcde0fb55fa719351b130d0c89594e20316e24244e73ecc99dfdf65683c0ff

You can always tell what wrote a line, under whose authority, and for which task. The filter is --entity: tovio log --entity agent for agent-authored commits, --entity human for the rest, and --task-id <id> for one task's trail. Agent sessions also show up live in tovio status, with their branch scope and time-to-expiry:

  1 active agent session(s):
    ⚡ cap_3b6d17f7f0136f62bd32825185a349a9  did:tovio:agent/claude-code  model anthropic:claude-opus-4-8 · branches agent/claude-code/** · expires in ~1h

Step 6 — Revoke when you're done¶

A token expires on its own, but you can pull it immediately. Revoking a token invalidates it and its entire delegated sub-tree at once:

tovio agent revoke cap_3b6d17f7f0136f62bd32825185a349a9

Revoked token cap_3b6d17f7f0136f62bd32825185a349a9.
  Removed did:tovio:agent/claude-code from the access registry — a copied session grant no longer authenticates.
token cap_3b6d17f7f0136f62bd32825185a349a9
  agent:       did:tovio:agent/claude-code
  model:       anthropic:claude-opus-4-8
  authorized:  did:key:f0dcde0fb55fa719351b130d0c89594e20316e24244e73ecc99dfdf65683c0ff (human)
  scope:       **  (excluding 0 protected path(s))
  branches:    agent/claude-code/**
  window:      [2026-09-09 11:16:17 -04:00, 2026-09-09 13:16:17 -04:00)  clearance=false
  object:      7e9285285b285eb90f48e84699e803ba642aac6884592219dd9b8360772197c4
  status:      REVOKED

The token is re-printed with status: REVOKED so you can see exactly what was withdrawn, and the agent's identity leaves the access registry — a copy of its session grant no longer authenticates.

What you learned¶

An agent gets a capability token: scoped to paths, short-lived, with safe defaults that deny dangerous operations and withhold secret clearance.
An agent without clearance cannot read protected files through TOVIO — enforced by cryptography, not a policy check it might bypass. Other tools and explicitly disclosed plaintext are out of scope.
Every agent commit carries provenance — model, task, authorizing human, signing device — and tovio log --entity agent|human (or --task-id) filters history by it.
You can revoke a token instantly, and the revocation cascades to everything it delegated.

This is what "AI agents as first-class participants" means in practice: bounded, attributable, and revocable — not a shared human credential handed to a bot.

Next¶

You've seen the whole arc — install, the daily loop, protected secrets, team collaboration, and bounded agents. To go deeper:

The ideas underneath it all: Core concepts.
The agent control plane in depth: AI agents & automation.
Bringing an existing project in: Migrate from Git.

Last reviewed September 9, 2026

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