Drive

VoltDrive is the part of tdx Volt that models a synchronised, shared file system: a logical tree of paths and files whose contents are kept consistent through the same sync database machinery as other collaborative data, while still looking like normal files and folders to tools and users.

Two resource kinds work together in the implementation:

Drive database

The drive database is a synapse resource that also carries the volt:drive-database kind. That synapse holds the replicated drive state (documents for file content and indexing, coordinated like any other synapse-backed data).

The drive database resource also describes the folder-sync settings that are used when a Volt keeps a directory on disk in step with that synapse: glob-based include and exclude lists, a maximum file size, and whether binary files are skipped. Those options apply to the Volt’s embedded folder synchronisation logic.

Drive instance

A drive instance (volt:drive-instance) is a separate resource that synchronises a drive database to a local folder path on the machine running that Volt process. Each instance records which synapse (the drive database) to follow as well as which folder to mirror.

An instance may also record how to reach the synapse when it does not live on the same Volt: remote Volt address details, relay settings, and related fields. So one physical Volt can run folder sync against a drive database that is authoritative on another Volt, as long as connectivity and policy allow it.

When a Volt starts, its drive subsystem loads every drive instance resource, initialises a worker for each, and keeps that worker running until the instance is removed or the Volt stops. Adding, updating, or removing a drive instance resource is reflected on the event bus, so new or changed instances are picked up without a full restart.

Policy and safety

Ordinary access to the data inside a drive database is governed by Volt policy like other databases: for example volt:database-read and volt:database-write on the underlying resource, as described under policy.

Creating or updating a drive instance is done via the Drive API SaveDriveInstance API. This is a privileged API call, because it entails access to the local disk on the machine that is running the Volt. Callers need the explicit volt:api-call permission granted for the volt:save-drive-instance permission.

Sharing the contents of a drive with other identities is still expressed through normal policy on the drive database (synapse) resource—for example database read or write—backed by verifiable credentials as elsewhere on the platform.

What you get in practice

  • One path namespace inside a drive database — familiar hierarchical names for files and directories.
  • Live replication of documents between clients and Volts that participate in the same synapse, subject to the usual sync and synapse rules.
  • Optional desktop sync — each drive instance ties one synapse-backed drive to one local directory on a Volt host, with include/exclude and file-size rules defined on the drive database resource.

Further reading

  • Drive Explorer — a web-based tool for exploring and managing drives.
  • Drive API — SaveDriveInstance and related types.
  • Synchronise JSON — SyncProvider for applications that edit drive documents without using folder sync.