Skip to content

Format reference

Every byte TOVIO writes to disk or sends over the wire is governed by a publicly versioned, documented format. This section describes those formats so that TOVIO users, auditors, integrators, and tool authors have a precise reference for what a TOVIO repository actually is.

This section is the front door to those formats. It summarizes each one precisely; the normative texts, with their REQ-* requirement IDs and RFC 2119 language, live in the repository under docs/specs/.

What the documented formats give you

Your history is yours, and it is stored in a format you can inspect. Concretely:

  • Your data outlives any one release. A TOVIO repository is a directory of content-addressed objects whose encoding is fully documented. The bytes on your disk remain readable, exportable, and auditable — you are never locked into a proprietary black box.
  • Protected reads have a cryptographic boundary. Policy-protected payloads use the crypto envelope, and merely storing or relaying those payloads does not provide a recipient private key or unwrapped data key. Public content, object and policy metadata, service availability, authorized endpoints, runners, and content explicitly disclosed to an agent or model remain separate trust boundaries.
  • Everything is auditable. Because the formats are written down, security reviewers, compliance auditors, and integrators can reason about exactly what is stored, what is transmitted, and what a capability token authorizes.
  • Changes are versioned in the open. Each format carries a version. Backward- compatible additions never break a reader; breaking changes follow a public deprecation policy with a documented migration.

Index of the formats

Specification What it governs Status
Storage format The on-disk object store: canonical CBOR, BLAKE3 addressing, FastCDC chunking, the .tovio/ layout. Format version 1
Wire protocol How two replicas sync: the HELLO/HAVE/WANT/OBJECTS exchange, sparse transfer, CRDT refs, and protected payload envelopes. tovio-wire/1 (frozen, Stable)
Crypto envelope The ABE-forward policy envelope: per-object DEK, per-recipient key wrap, the fixed primitive set. Format version 1
Policy & tokens The policy expression language and the capability-token contract that authorizes agents. tovio-capability-v1
Conformance The byte-for-byte fixture corpus used to test that the reference implementation encodes and addresses objects correctly. Versioned with the format

Licensing of these specifications

TOVIO uses a per-component ("open-core") licensing model:

  • The core engine and CLI — tovio-core, tovio-cli, tovio-proto, tovio-node-bindings, tovio-index and tovio-store, the provider-neutral tovio-keystore contracts, the runner-neutral CI job contract (tovio-ci-core), the TypeScript SDKs and edges, and the specification and conformance corpus themselves — are Apache-2.0 (OSI-approved open source).
  • The Forge — tovio-forge and the shared tovio-forge-domain, the tovio-web-ui dashboard, the hosted CI platform (tovio-ci-orchestrator, tovio-ci-runner, tovio-webauthn), and the hosted edge realization — is a proprietary commercial product (SPDX: LicenseRef-TOVIO-Commercial). Elastic-2.0 was retired from this project (ADR-0312). Only TOVIO operates the Forge as a service and only TOVIO distributes the binary. The TOVIO Cloud control plane, the private Cloudflare adapter, and the enterprise connectors are the same commercial code.
  • The free tier is tovio serve, in the Apache-2.0 CLI above: a real bidirectional TLS server that clones, fetches, pushes, and enforces your per-file permission policy on every push, without the collaboration platform.
  • Enterprise modules — the enterprise crypto and Key Authority, the LDAP/SAML/SCIM connectors, the shared onboarding contract, and the managed-service implementations — are commercial / proprietary, and none of them is included in any Apache-licensed package or release artifact.

The authoritative texts are LICENSE and LICENSE-APACHE at the repository root, with the per-component overview in LICENSE. "TOVIO" is a trademark of the TOVIO project; none of these licenses grant a right to use the TOVIO name or marks — the naming policy is TRADEMARK.md at the repository root.

How these documents relate

The formats build on one another in a fixed order of precedence:

  • The storage format is the bytes. Where any other spec appears to disagree about the bytes of an object, the storage format governs.
  • The data model (the logical object schema) gives those bytes meaning. The crypto envelope and policy specs refine specific object types defined there.
  • The wire protocol moves storage-format bytes between machines without re-encoding them — an object hashes the same on disk and in flight.
  • The crypto envelope and policy & tokens specs define the permission objects and the rules for reading and writing them.

Where to go next

  • New to TOVIO? Start with the concepts for the ideas behind these formats.
  • Building on top of TOVIO? See the reference and integrations — most tools should integrate through the CLI, SDKs, or MCP surface rather than by re-implementing these formats.

Last reviewed September 9, 2026

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