Architecture

Tonbo Artifacts splits into three planes. Each fails independently; a problem in one doesn't propagate to the others.

The three planes

Plane	Where it lives	What it holds
Data plane	Your S3 bucket (BYO) or a Tonbo-managed S3 prefix	Immutable file chunks (≤4 MiB blocks)
Metadata plane	Tonbo-operated metadata store	Per-workspace directory tree, file index, per-mount permissions
Control plane	Tonbo Orchestrator API	Auth, workspace lifecycle, mount-session issuance

On the customer host, a sidecar agent process (the artifacts binary, started by artifacts mount) serves the FUSE mount. It owns the on-disk metadata + chunk cache and talks to the metadata and data planes directly. The control plane is not in the read/write path. It shows up only on login, workspace create/delete, and the initial mount-session handshake.

        Agent VM                      Tonbo                        S3
        --------                      -----                        --

   +-----------------+        +--------------------+
   |   FUSE mount    |        |   Orchestrator     |
   |                 |  <-->  |  (control plane)   |
   |  sidecar agent  |        +--------------------+
   |     process     |
   |                 |        +--------------------+
   |   local cache   |  <-->  |   Metadata store   |
   +-----------------+        +--------------------+
           |
           |  chunks (read / write)
           +-------------------------------------------------> +--------+
                                                               | chunks |
                                                               +--------+

Failure isolation

If this is unavailable	Existing mounts	New operations
Orchestrator	Reads and writes continue; metadata flows directly between the sidecar and the metadata store	login, workspace create/delete, mount blocked
Metadata store	Cached lookups still serve from the sidecar; uncached lookups and metadata writes return errors	Mounts that need fresh metadata fail to start
Chunk store (S3)	Cached chunks read normally; uncached reads block until S3 returns	Writes buffer to local cache, then back-pressure
Sidecar agent process	That host's mount stops responding; artifacts mount re-establishes it. Other hosts unaffected.	Other hosts unaffected
Agent VM	Nothing on the workspace is lost. Chunks remain in S3, metadata in the metadata store.	None

Durability

No customer data ever lives only on the agent VM. The local cache is a performance artifact; losing it is a latency event, not a data event.

Chunks (data plane). Chunks are written to S3 on file close and on explicit fsync. S3 provides eleven nines of durability. In BYO mode, your bucket's existing properties (versioning, replication, lifecycle) apply unchanged.

Metadata (metadata plane). Metadata updates are committed to the metadata store before the originating operation (or fsync) returns. The metadata store rotates a full snapshot to a separate S3 region at least daily. Recovery from process crash is log replay on the metadata store; recovery from host loss is snapshot restore.

Chunks and the index. A chunk's object key is a sequential slice id assigned by the metadata store, not a content hash; the same bytes written twice land in different chunks. The file-to-chunk index lives in the metadata store, so backup, restore, and migration move that metadata snapshot alongside the chunks rather than reconstructing the index from the bucket.

Isolation

Each workspace is a separate namespace inside the metadata store. A mount-session token is scoped to exactly one workspace; it cannot enumerate or read any other workspace's metadata, even within the same organization.

In managed mode, the data plane is scoped the same way. The IAM credentials issued to a mount session can only read or write within that workspace's S3 prefix.

In BYO mode, S3 credentials never leave the customer host. The orchestrator never holds them and the metadata store never holds them. A Tonbo operator with full operational access to either plane cannot read your bytes.

Exit

In BYO mode the customer owns the data path end-to-end. Chunks live under documented prefixes in your bucket as stable, immutable objects readable by any S3-aware tool (aws s3 sync, rclone, s3cmd) without Tonbo running and without Tonbo's permission. Reconstructing files (names, tree, permissions) additionally needs the metadata index, which Tonbo holds; the bytes themselves are never locked to Tonbo.