# IronShard — products and full documentation

> The governed data layer for AI agents: S3-compatible storage agents connect to over MCP, with instant production forks, zero-egress reads, per-agent access control, and a signed audit trail.

Generated at build time. Product sections first (the current offering), followed by the complete technical documentation. Canonical HTML pages live at the URL noted in each section. A curated index is available at https://www.ironshard.ai/llms.txt.

---

## IronShard Platform

URL: https://www.ironshard.ai/

> The governed data layer for AI agents — S3-compatible storage agents connect to over MCP.

IronShard is an S3-compatible bucket your agents connect to over MCP, with a live fork of production they can safely work on, zero egress on every read, per-agent access control, and a signed record of everything they touch.

Core capabilities:

- S3-compatible API — works with AWS CLI, boto3, s3fs, rclone, Terraform, Airflow, LangChain, MLflow, PyTorch, Apache Spark, DVC, and Prefect without SDK changes
- MCP-native agent access
- Instant zero-copy production forks
- Zero-egress reads
- Per-agent access control
- Cryptographically signed audit trail
- Automated cost-based storage routing

IronShard is in early access. Request access at https://www.ironshard.ai/waitlist.

---

## AI Agent Storage

URL: https://www.ironshard.ai/agents

> Authenticated, policy-governed storage access for autonomous AI agents, with immutable audit trails, fine-grained access control, and MCP compatibility.

IronShard gives AI agents authenticated, policy-governed access to object storage. Every agent request flows through the same pipeline: request → authenticate (per-agent credentials) → policy check (approved or blocked) → log (immutable record written and signed) → serve.

Key facts:

- **MCP support:** IronShard exposes storage, metadata, and audit APIs via MCP, so agents interact with data through structured endpoints without custom integration work.
- **Framework compatibility:** works with any framework that supports S3-based storage, including LangChain, AutoGen, LlamaIndex, CrewAI, OpenAI function calling, PyTorch, TensorFlow, MLflow, HuggingFace, and Airflow. No SDK changes required.
- **Logging:** every request made by an authenticated agent (reads, writes, queries, inferences) is automatically written to an immutable, cryptographically signed audit log — searchable, filterable, and exportable. No instrumentation required.
- **Per-agent access levels:** each agent gets its own credentials with a defined scope (read-only, write-only, admin, or custom). Policies are enforced at the storage layer and can be updated without redeploying the agent.
- **EU AI Act:** versioning, lineage tracking, and immutable audit logs provide the documented data lineage, auditability, and reproducibility the EU AI Act requires.
- **No migration needed:** IronShard connects to existing S3-compatible buckets; current infrastructure stays in place. IronShard-managed storage is also available, or a combination of both.
- **Multi-agent workflows:** each agent operates within its own access scope; multiple agents run in parallel against the same datasets, and branching lets agents work on isolated copies of production data simultaneously with full audit trails per branch.

---

## Mirror

URL: https://www.ironshard.ai/mirror

> A live, governed copy of production for AI — always current, fully isolated, branchable, and automatically logged.

Your AI needs real data; production needs to stay untouched. Mirror keeps a live, governed copy of your production S3: always current, fully isolated, and automatically logged. Production is never touched, and access is controlled per agent.

- The mirrored copy stays current with production — no stale snapshots or manual refresh pipelines.
- AI workloads experiment on the mirror, never on production.
- Any mirrored bucket can be branched for isolated experiments (see Branch), keeping results reproducible.
- All access to the mirror is logged automatically.

---

## Branch

URL: https://www.ironshard.ai/branch

> Point-in-time-recoverable, infinitely forkable workspaces — immutable snapshots, zero-copy branches, governed promotion with an automatic audit trail.

Branch turns any IronShard bucket — mirrored or native — into a point-in-time-recoverable, infinitely forkable workspace. Snapshot any bucket, branch it instantly, recover anything.

- **Immutable snapshots:** snapshots accrue on main; restore to any snapshot at any time.
- **Zero-copy branches:** spin up an isolated copy-on-write branch, run a job, check the results, then promote or discard. Nothing touches the source until you say so. No object duplication, no copy costs.
- **Governed promotion:** when work is done, IronShard shows exactly what changed — added, modified, removed objects, plus cost and policy impact — and a human decides: promote (merge back), keep as audit artifact, or discard. Nothing ships without approval.

Full technical details: https://www.ironshard.ai/docs/branching

---

## Log

URL: https://www.ironshard.ai/log

> A tamper-proof, exportable record of every file access, read, write, and query made by AI tools.

Know what your AI did — exactly. Connect IronShard Log to your agent in minutes; from that point forward, every file access, read, and write is logged automatically, tamper-proof, and exportable. No infrastructure changes, no custom pipelines.

- **What gets logged:** every query, every file, every action — with a timestamp, an agent ID, and a reason when the workflow provides one.
- **Evidence, not just logs:** records are immutable; they cannot be edited, deleted, or backdated. What happened, happened, and you can prove it.
- **Built for the audit question:** "Which data did your AI use to make that decision?" — the answer is already there: structured, signed, and exportable in one click.
- **Works with existing tools:** connects to any S3-compatible storage. If something can read a file, IronShard Log can record it.

---

## Trim

URL: https://www.ironshard.ai/trim

> S3 cost arbitrage — analyses your bucket's access pattern, identifies your workload type, and routes data to the cheapest compatible provider.

Trim analyses your S3 bucket's actual access pattern, identifies your workload type, and automatically routes your data to the cheapest compatible provider (candidates include Cloudflare R2, Backblaze B2, Wasabi, Exoscale, and DigitalOcean Spaces).

- **S3 cost arbitrage:** different providers price egress, requests, and storage very differently. A workload that is expensive on AWS S3 may be significantly cheaper on Cloudflare R2 or Wasabi, depending on how the data is accessed.
- **No application changes:** Trim works through IronShard's S3-compatible endpoint. Existing tools, SDKs, and pipelines keep using the same endpoint and credentials; provider routing happens transparently.
- **Workload types:** egress-heavy workloads (data frequently downloaded by external parties) benefit from zero-egress providers; throughput-heavy workloads (high request volumes from AI training, batch processing, analytics) benefit from providers without per-request fees.
- **Resilience:** IronShard fragments data before distributing it across providers — each provider holds only partial, encrypted fragments, so no single provider can reconstruct files or become a single point of failure. A provider outage does not affect availability; IronShard rebalances automatically.

---

## Documentation

URL: https://www.ironshard.ai/docs

> IronShard documentation — governed, S3-compatible object storage built for AI agents. Agent access via MCP, platform architecture, and compliance.

# IronShard Documentation

IronShard is governed, S3-compatible object storage built for AI agents. Autonomous agents can create and operate real buckets through a public MCP server without an account, OAuth, or payment. Teams get multi-cloud durability through erasure-coded fragmentation, fine-grained access policies, and immutable audit logs for every human and agent action.

## For AI Agents

Autonomous agents are permitted to create and use IronShard buckets without human approval. Connect to the public Agent MCP server at `https://mcp.agent.ironshard.ai/mcp` and call `create_bucket` — no authentication is required for creation.

- [Agent Buckets](/docs/agent-buckets) — Complete specification of the public Agent MCP server: available tools, request and response shapes, S3-compatible credentials, limits, the guided validation workflow, and handoff for adoption into a tenant.

## Platform

How IronShard stores, protects, and serves data.

- [System Architecture](/docs/system-architecture) — The three-layer design: S3-compatible gateways, a globally consistent metadata plane, and a multi-cloud storage fabric.
- [API Compatibility and Extensibility](/docs/api-compatibility) — AWS S3 API compatibility, so existing SDKs, pipelines, and tools connect without code changes.
- [Storage Classes](/docs/storage-classes) — Budget, Standard, and Performance classes with adaptive redundancy and flat per-class pricing.
- [Branching and Snapshots](/docs/branching) — Point-in-time snapshots and copy-on-write branches for isolated experiments on real data without duplicating buckets.
- [Secure Ingest Pipeline](/docs/ingest-pipeline) — The compress → encrypt → erasure-code → distribute sequence every object passes through on write.
- [Resilience and Adaptive Redundancy](/docs/resilience) — Erasure-coded fragments across providers and regions: durability above triple replication at a fraction of the overhead.
- [Intelligent Caching](/docs/intelligent-caching) — Predictive, geo-aware fragment placement and cache warm-up for low-latency access.

## Compliance

How IronShard meets data-protection and sovereignty requirements.

- [Security and Data Sovereignty](/docs/security-and-data-sovereignty) — Encryption at every stage, geo-fencing, placement policies, and immutable audit logs across multiple clouds.
- [GDPR Everywhere](/docs/gdpr-everywhere) — Provider-independent privacy: encrypted fragments mean no single cloud ever holds a complete, readable file.

---

## System Architecture

URL: https://www.ironshard.ai/docs/system-architecture

> "How IronShard works: S3-compatible gateways, a globally consistent metadata plane, and an erasure-coded multi-cloud storage fabric."

# System Architecture

IronShard is a multi-cloud object storage designed for data sovereignty, resilience and heavy AI workloads. It combines a globally distributed architecture with advanced erasure coding, predictive caching, and adaptive placement to deliver low-latency access with an optimised storage footprint.

## Multi-Layered Design

IronShard is built around three independent but tightly coordinated layers:

- **Gateway Layer:** Regional entry points exposing the S3-compatible API. They authenticate requests, perform caching, and route data to the nearest storage zone.
- **Metadata Plane:** A globally consistent metadata system tracking every object's location, lineage, and redundancy level.
- **Storage Fabric:** Distributed data nodes storing encoded fragments across multiple regions and providers for maximum durability.

This modular design allows each layer to scale and evolve independently, enabling global reach without centralized bottlenecks.

## Distributed Redundancy and Resilience

Instead of multiple replicas, IronShard applies **erasure coding** to divide object contents into *k* slices and generate *k + m* encoded fragments with random coefficients. Any *k* can reconstruct the object, but less than *k* carry no recoverable information. The number of fragments (*k* and *m*) depends on the [Storage Class](/docs/storage-classes) of the object, where higher classes apply more redundancy for improved availability and locality.

This approach delivers:

- **Higher durability** than the industry-standard replication
- **Reduced storage overhead:** Significantly less additional storage is required by erasure coding to achieve the same durability level as replication
- **Cloud-agnostic fault tolerance:** Fragments live across regions of different cloud providers
- **Lower environmental footprint** due to less data stored and transferred

## Intelligent Caching and Geo-Awareness

Each gateway maintains a **local cache** of encrypted object slices, that adapts to access patterns. Data that is frequently used or predicted to be needed stays near common traffic origins, while scheduled workloads can proactively use **cache-warmup requests**.

The result is:

- Millisecond-class access for hot objects
- Lower latency for globally distributed teams and their applications or users
- Reduced inter-region traffic and costs

## Secure Ingest Pipeline

Every object entering IronShard passes through a multi-stage ingest pipeline designed for **efficiency and confidentiality**:

1. **Compression:** Data is compressed using adaptive algorithms that balance throughput and size reduction.
2. **Encryption:** Compressed data is encrypted with per-slice, cryptographically secure random keys, ensuring end-to-end confidentiality.
3. **Erasure Coding:** Encrypted slices are erasure-coded into redundant fragments.
3. **Distribution:** The resulting compressed-encrypted-encoded fragments are placed in cloud storage regions, chosen based on access patterns of similar objects, respecting the bucket or object-level geo-fence restrictions if present.

This *compress → encrypt → encode → distribute* sequence guarantees that data remains **lightweight, secure, and durable** throughout its lifecycle.
It also means that fragments are **individually useless** without the full reconstruction process, adding an inherent layer of security against unauthorized access or overly curious cloud providers.

## Adaptive Storage Representation

IronShard continuously evaluates sub-object access patterns and automatically adjusts their redundancy and placement across the storage fabric.

### Standard Class: Reactive Optimization

Objects start with a baseline redundancy level. When traffic increases, IronShard **reactively** expands the number of fragments or redistributes them closer to active regions.
When demand drops, redundancy is gradually normalized to conserve space and bandwidth.

### Performance Class: Proactive, ML-Driven Optimization

A predictive model forecasts **where and when** data will be accessed next, based on historical behavior, geolocation trends, and bucket activity.
IronShard proactively loads the slices to cache and may adjust fragment counts and placement *before* demand spikes, ensuring sub-millisecond access from the most relevant regions.

This **traffic-aware storage evolution** keeps costs low on standard workloads and delivers consistent high performance under heavy or distributed demand without manual tuning. By rebalancing the underlying fragments to match sustained traffic patterns we avoid depending on large caches in every gateway instance, lowering costs while achieving millisecond-class p95 latency and throughput comparable to fully cached CDNs.


<!-- [Note: this entire section is commented out until the compatibility matrix is published]
## API Compatibility and Extensibility

IronShard speaks the **AWS S3 API**, providing compatibility with existing clients and SDKs.
For a detailed list of supported S3 Actions, see our [S3 Compatibility Matrix](/docs/overview/s3-compatibility).
-->

## Security and Data Sovereignty

Security is intrinsic to IronShard's architecture:

- Encryption at rest and in transit
- Cryptographic keys held exclusively by a tamper-resistant <abbr title="Key Management System">KMS</abbr>
- Geo-fence at the bucket or individual object level
- Comprehensive audit logs

Organizations maintain full control over *where* data lives and *who* can access it.

## Performance by Design

IronShard's async and event-driven design supports **parallel I/O, pipelined transfers, and region-aware routing**, resulting in:

- Near-edge read/write latency
- High throughput for large parallel workloads
- Efficient background prefetching and write aggregation

## Summary

| Design Choice | Real-World Benefit |
|----------------|--------------------|
| Compress → Encrypt → Encode pipeline | Secure, bandwidth-efficient ingestion |
| Erasure coding across clouds | High durability with lower cost |
| Adaptive redundancy | Optimal balance between performance and resource use |
| Predictive caching | Instant access with minimal latency |
| S3 compatibility | Immediate usability and long-term interoperability |

By combining **distributed intelligence**, **adaptive encoding**, and **multi-cloud resilience**, IronShard redefines what cloud storage can be **fast, sovereign, and sustainable**.

---

## Agent Buckets

URL: https://www.ironshard.ai/docs/agent-buckets

> Autonomous AI agents can discover IronShard, create a real bucket through the public Agent MCP server, use IronShard-native object storage features, and optionally hand the bucket off to an owner — without tenant OAuth.

# Agent Buckets

IronShard provides a **public Agent MCP server** for autonomous AI agents that need object storage. They can discover IronShard, create a real IronShard bucket, store and retrieve objects, use IronShard-native features such as snapshots and branch/diff/merge, validate the core workflow, and optionally hand the bucket off to a human owner or supervising agent.

Buckets created through the Agent MCP server are real IronShard buckets with bucket-scoped credentials. They are separate from tenant-owned production buckets until they are adopted into an authenticated IronShard account.

**Permission**: Autonomous agents **are permitted** to create buckets through the public Agent MCP server without human approval, tenant OAuth, or an existing IronShard account. These buckets are controlled by bucket-scoped credentials returned at creation time.

## Two MCP servers

IronShard exposes two separate MCP surfaces.

| Surface | Purpose | Auth |
| --- | --- | --- |
| Public Agent MCP server | Autonomous bucket creation, object storage, snapshots, branches, diffs, merges, validation, and handoff | No OAuth required. Bucket operations use the `bucket_id` and `bucket_token` returned by `create_bucket`. |
| Production MCP server | Tenant-owned buckets, connected buckets, governance, agent credentials, policies, audit, and organization settings | OAuth required on every tool. A human, organization, or authorized agent must have access to an IronShard tenant. |

The same storage concepts exist on both servers, but the authority model is different.

* On the Public Agent MCP server, `create_bucket` creates a bucket through the public agent flow and returns bucket-scoped credentials.
* On the Production MCP server, `create_bucket` creates a tenant-owned production bucket using OAuth and account policy.

## Connect

Connect your agent to the public Agent MCP server.

| Field | Value |
| --- | --- |
| Protocol | Model Context Protocol (MCP) |
| Public Agent MCP server | `https://mcp.agent.ironshard.ai/mcp` |
| Initial tool | `create_bucket` |
| MCP auth | None required for bucket creation |

*Note: Technical values on this page are provisional and may change before launch.*

## Public Agent MCP tools

The Agent MCP server exposes tools for creating and operating buckets directly from autonomous agent workflows.

| Tool | Purpose |
| --- | --- |
| `create_bucket` | Creates a bucket through IronShard's public Agent MCP flow without tenant OAuth. Returns `bucket_id`, `bucket_token`, limits, connection instructions, and handoff information. |
| `get_bucket` | Returns metadata about a bucket created through the Agent MCP server, including status, lifecycle settings, limits, and available capabilities. |
| `get_bucket_usage` | Returns current storage, request, object-count, and egress usage for the bucket. |
| `extend_bucket` | Extends the bucket lifetime or operating window if the bucket policy allows it. |
| `revoke_bucket` | Revokes the bucket and disables further access to its data and credentials. |
| `generate_bucket_handoff` | Generates a human- or super-agent-facing handoff summary with management links and validation evidence. |
| `put_small_object` | Writes a small inline object directly through MCP for quick agent-native storage operations. |
| `get_small_object` | Reads a small object directly through MCP when the object is within inline response limits. |
| `create_object_upload_url` | Creates a short-lived presigned URL for uploading an object to the bucket. |
| `create_object_download_url` | Creates a short-lived presigned URL for downloading an object from the bucket. |
| `list_objects` | Lists objects in the bucket, optionally filtered by prefix. |
| `delete_object` | Deletes an object from the bucket. |
| `get_object_metadata` | Returns object metadata, including size, version, checksum, content type, and timestamps. |
| `copy_object` | Copies an object within the bucket. |
| `create_snapshot` | Creates a point-in-time snapshot of the bucket or selected object prefix. |
| `list_snapshots` | Lists snapshots available in the bucket. |
| `get_snapshot` | Returns metadata for a specific snapshot. |
| `restore_snapshot` | Restores data from a snapshot into the bucket. |
| `delete_snapshot` | Deletes a snapshot if bucket policy allows deletion. |
| `create_branch` | Creates a writable branch from the current bucket state, a snapshot, or another branch. |
| `list_branches` | Lists branches in the bucket. |
| `get_branch` | Returns metadata and status for a specific branch. |
| `delete_branch` | Deletes an unneeded branch and its unmerged changes. |
| `put_small_object_on_branch` | Writes a small inline object to a specific branch. |
| `get_small_object_from_branch` | Reads a small object directly from a specific branch. |
| `create_branch_object_upload_url` | Creates a presigned upload URL for writing an object to a specific branch. |
| `create_branch_object_download_url` | Creates a presigned download URL for reading an object from a specific branch. |
| `list_objects_on_branch` | Lists objects visible on a specific branch. |
| `delete_object_on_branch` | Deletes an object on a branch without affecting the main bucket state until merge. |
| `get_branch_object_metadata` | Returns metadata for an object as seen on a specific branch. |
| `diff_branch` | Computes the difference between a branch and its base or target branch. |
| `get_diff` | Returns details for a previously computed diff, including added, modified, deleted, and conflicting objects. |
| `merge_branch` | Merges branch changes into the target branch or main bucket state. |
| `discard_branch` | Discards branch changes without merging them. |
| `get_audit_log` | Returns audit events for bucket operations, including object writes, reads, branch changes, merges, and credential actions. |
| `explain_policy_decision` | Explains why a bucket operation was allowed or denied. |
| `revoke_bucket_credentials` | Revokes active bucket credentials without necessarily deleting the bucket. |
| `validate_core_workflow` | Runs a guided validation of IronShard's core workflow and returns artifacts the agent can independently verify. |
| `generate_validation_report` | Produces a structured validation report summarizing what the agent tested and what evidence was produced. |
| `get_connection_instructions` | Returns MCP, presigned URL, and optional S3-compatible connection instructions for the bucket. |

The tools are regular MCP tools, but they are not tenant tools. After `create_bucket`, bucket operations require the `bucket_id` and `bucket_token` returned by the Agent MCP server.

## Create a bucket

The agent starts by calling `create_bucket`. An optional `label` can be used to identify the bucket in later handoff or audit views.

```json
// tool call
{
  "tool": "create_bucket",
  "input": {
    "label": "research-artifacts",
    "intended_use": "Store PDFs, extracted tables, and report artifacts for a market research task."
  }
}
```

Example response:

```json
{
  "bucket_id": "agb_9f3a21c0",
  "bucket_type": "agent_issued",
  "status": "active",
  "bucket_token": "ist_bucket_...",
  "created_via": "public_agent_mcp",
  "connection_instructions": {
    "mcp": {
      "server_url": "https://mcp.agent.ironshard.ai/mcp",
      "auth_model": "bucket_id_and_bucket_token"
    },
    "s3": {
      "endpoint": "https://s3.agent.ironshard.ai",
      "region": "eu-central",
      "bucket": "agb-9f3a21c0",
      "access_key_id": "ISK...",
      "secret_access_key": "ISS..."
    }
  },
  "limits": {
    "max_total_storage_gb": 5,
    "max_object_size_gb": 1,
    "max_objects": 10000,
    "max_requests_per_day": 10000,
    "external_bucket_connections": false,
    "billing": false
  },
  "handoff": {
    "url": "https://console.ironshard.ai/adopt/agb_9f3a21c0?...",
    "message": "This bucket was created through IronShard's public Agent MCP server and can be adopted into an IronShard tenant if desired."
  },
  "recommended_next_tool": "validate_core_workflow"
}
```

The `bucket_token` is not an OAuth token and does not identify a tenant. It is a bucket-scoped credential used with the public Agent MCP tools. If S3-compatible access is returned, those credentials are also scoped to the created bucket.

## Store objects

Agents can store small objects directly through MCP or request presigned URLs for larger objects.

Small inline write:

```json
// tool call
{
  "tool": "put_small_object",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "key": "notes/summary.json",
    "content_type": "application/json",
    "content": "{\"status\":\"ok\"}"
  }
}
```

Presigned upload URL:

```json
// tool call
{
  "tool": "create_object_upload_url",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "key": "reports/final.pdf",
    "content_type": "application/pdf"
  }
}
```

Example response:

```json
{
  "upload": {
    "method": "PUT",
    "url": "https://s3.agent.ironshard.ai/agb-9f3a21c0/reports/final.pdf?...",
    "expires_at": "2026-10-15T12:30:00Z",
    "required_headers": {
      "content-type": "application/pdf"
    }
  },
  "object": {
    "bucket_id": "agb_9f3a21c0",
    "key": "reports/final.pdf"
  }
}
```

The upload URL writes the object directly. There is no separate completion step for simple uploads. Presigned URLs are short-lived and expire a short time after they are issued, so `expires_at` is always relative to when the URL is created.

## Use branches

IronShard branches let an agent make changes without immediately changing the main bucket state.

```json
// tool call
{
  "tool": "create_branch",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "branch": "analysis-draft",
    "base": "main"
  }
}
```

The agent can then write to the branch:

```json
// tool call
{
  "tool": "put_small_object_on_branch",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "branch": "analysis-draft",
    "key": "notes/summary.json",
    "content_type": "application/json",
    "content": "{\"status\":\"revised\"}"
  }
}
```

Before merging, the agent can inspect the diff:

```json
// tool call
{
  "tool": "diff_branch",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "branch": "analysis-draft",
    "target": "main"
  }
}
```

## Validate the core workflow

After creating a bucket, the recommended next step is to call `validate_core_workflow`.

This tool runs a predefined validation workflow using IronShard's object storage, snapshot, branch, diff, merge, policy, and audit primitives. It is designed to give autonomous agents a short, reliable way to test the product's core claims.

```json
// tool call
{
  "tool": "validate_core_workflow",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "profile": "core_workflow_v1"
  }
}
```

The workflow validates:

* object write and read
* checksum and metadata integrity
* object listing
* snapshot creation
* writable branch creation
* branch-local object mutation
* diff generation
* merge into main
* audit log visibility
* policy denial for a forbidden operation
* usage and limit reporting

The tool does not merely return a pass/fail result. It returns artifacts that the agent is encouraged to verify with other Agent MCP tools.

Example response:

```json
{
  "status": "passed",
  "bucket_id": "agb_9f3a21c0",
  "bucket_type": "agent_issued",
  "validation_id": "val_6c41",
  "validation_profile": "core_workflow_v1",
  "validated_capabilities": [
    {
      "capability": "object_write_read",
      "status": "passed",
      "evidence": {
        "key": "validation/core/hello.txt",
        "version_id": "ver_001",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015..."
      }
    },
    {
      "capability": "branch_diff_merge",
      "status": "passed",
      "evidence": {
        "source_branch": "main",
        "test_branch": "branch_val_001",
        "diff_id": "diff_456",
        "merge_id": "merge_123",
        "changed_keys": [
          "validation/core/hello.txt",
          "validation/core/new-file.json"
        ]
      }
    },
    {
      "capability": "policy_enforcement",
      "status": "passed",
      "evidence": {
        "attempted_action": "connect_external_bucket",
        "expected_result": "denied",
        "denial_reason": "external_bucket_connections_disabled_for_public_agent_buckets",
        "audit_event_id": "evt_denied_001"
      }
    },
    {
      "capability": "auditability",
      "status": "passed",
      "evidence": {
        "audit_event_ids": [
          "evt_001",
          "evt_002",
          "evt_003",
          "evt_denied_001"
        ]
      }
    }
  ],
  "verification_artifacts": {
    "objects": [
      {
        "key": "validation/core/hello.txt",
        "expected_sha256": "9f86d081884c7d659a2feaa0c55ad015..."
      },
      {
        "key": "validation/core/new-file.json",
        "expected_sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e..."
      }
    ],
    "diffs": [
      {
        "diff_id": "diff_456",
        "expected_changed_keys": [
          "validation/core/hello.txt",
          "validation/core/new-file.json"
        ]
      }
    ],
    "audit_events": [
      "evt_001",
      "evt_002",
      "evt_003",
      "evt_denied_001"
    ]
  },
  "suggested_verification_calls": [
    {
      "tool": "get_object_metadata",
      "reason": "Verify the object exists and its checksum matches the expected hash.",
      "arguments": {
        "bucket_id": "agb_9f3a21c0",
        "bucket_token": "<reuse bucket token>",
        "key": "validation/core/hello.txt"
      }
    },
    {
      "tool": "get_diff",
      "reason": "Verify the branch diff contains the expected changed keys.",
      "arguments": {
        "bucket_id": "agb_9f3a21c0",
        "bucket_token": "<reuse bucket token>",
        "diff_id": "diff_456"
      }
    },
    {
      "tool": "get_audit_log",
      "reason": "Verify that successful and denied operations were recorded.",
      "arguments": {
        "bucket_id": "agb_9f3a21c0",
        "bucket_token": "<reuse bucket token>",
        "event_ids": [
          "evt_001",
          "evt_002",
          "evt_003",
          "evt_denied_001"
        ]
      }
    }
  ],
  "summary": {
    "headline": "IronShard core workflow validated in an agent-created bucket.",
    "recommended_next_action": "Continue using this bucket, or hand it off for adoption into an IronShard tenant.",
    "handoff_url": "https://console.ironshard.ai/adopt/agb_9f3a21c0?..."
  }
}
```

## Verify the artifacts

Agents should treat `validate_core_workflow` as a guided validation, not as blind trust. The returned artifacts can be inspected with lower-level Agent MCP tools.

Example metadata verification:

```json
// tool call
{
  "tool": "get_object_metadata",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "key": "validation/core/hello.txt"
  }
}
```

Example diff verification:

```json
// tool call
{
  "tool": "get_diff",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "diff_id": "diff_456"
  }
}
```

Example audit verification:

```json
// tool call
{
  "tool": "get_audit_log",
  "input": {
    "bucket_id": "agb_9f3a21c0",
    "bucket_token": "ist_bucket_...",
    "event_ids": [
      "evt_001",
      "evt_002",
      "evt_003",
      "evt_denied_001"
    ]
  }
}
```

## Handoff and adoption

A bucket created through the Agent MCP server can be used by the agent immediately. Human adoption is optional, not required for the bucket to be useful.

If the agent wants to notify an owner or supervising agent, it can call `generate_bucket_handoff` or use the handoff URL returned by `create_bucket`.

The handoff can include:

* the bucket ID and label;
* the reason the agent created the bucket;
* validation reports and verification artifacts;
* usage and object summaries;
* audit events;
* links for a human or organization to adopt the bucket into a production IronShard tenant.

When a bucket is adopted into a tenant:

1. The bucket becomes tenant-owned and manageable through the Production MCP server;
2. The bucket audit log and validation artifacts remain visible to the tenant;
3. Existing bucket-scoped credentials can be revoked, preserved temporarily, or converted into managed agent credentials, depending on tenant policy;
4. Future production operations use normal MCP OAuth and account-level policy;
5. Production tools become available according to the granted tenant scopes.

The public Agent MCP server does not issue tenant OAuth credentials.

## Constraints

Buckets created through the Agent MCP server are bounded by policy. Exact limits are provisional and may change before launch.

* Bucket credentials are scoped to one bucket.
* Bucket credentials are not OAuth tokens and do not grant tenant access.
* Default storage, object-count, request, and egress limits apply.
* Optional S3-compatible credentials, if issued, are scoped to the created bucket.
* External bucket connectors are not available through the public Agent MCP server.
* Billing, organization settings, team management, and tenant policies are not available through the public Agent MCP server.
* Every bucket operation is recorded in the bucket audit log.
* Bucket credentials can be revoked with `revoke_bucket_credentials` or by revoking the bucket.
* Abuse controls and rate limits may apply to public bucket creation and operation.

## Production access

Production IronShard access is intentionally separate from public agent bucket creation.

Authenticated production tools are exposed only by the Production MCP server at `https://mcp.ironshard.ai/mcp` and require normal MCP OAuth. Agents cannot obtain tenant access, billing access, organization access, or production policy control by calling the public Agent MCP server.

---

## Security and Data Sovereignty

URL: https://www.ironshard.ai/docs/security-and-data-sovereignty

> Encryption at every stage, geo-fencing, storage placement policies, and immutable audit logs — how IronShard enforces sovereignty across multiple clouds.

# Security and Data Sovereignty

## Geo-Distributed, Multi-Provider Storage

IronShard's security and sovereignty core principle is to **never rely on a single cloud provider, region, or execution environment**. Every object is encrypted, sharded, and distributed across multiple providers and geographic locations. You retain full authority over where data lives, how it moves, and which humans or AI agents can interact with it.

**Key Benefits:**

* Provider-agnostic data reconstruction
* Cloud providers never store complete files
* Geo-fencing for local data residency requirements
* Regulatory and security controls across multiple clouds
* Cloud lock-in and data concentration risks are minimized
* Regional or provider infrastructure failures do not impact availability

### Cloud-Agnostic Fault Tolerance

IronShard stores encrypted redundant object fragments across independent cloud platforms and regions, creating true multi-cloud resilience. Even a full provider outage does not disrupt access or data reconstruction.

### Geo-Fencing at Bucket or Object Level

Define approved regions for each bucket or individual object. IronShard automatically blocks storage, caching, or reconstruction outside permitted zones.

### Storage Placement Policies

Choose which providers and regions receive fragments. Combine AWS, GCP, Azure, and on-prem storage with precise, predictable placement control.

### Access Governance

IronShard merges multi-cloud freedom with strict, enforceable governance. Every reconstruction request is validated against your access policies before any fragment is assembled or decrypted.

AI systems inherit your access policies, preventing model overreach, data oversharing, or cross-region leakage caused by autonomous agents.

## Encryption at Every Stage

All fragments are encrypted in transit and at rest. Storage providers only hold encrypted fragments that have no standalone meaning.

**Encryption Guarantees:**

* Only authorized clients can initiate reconstruction
* Individual cloud providers cannot interpret fragment contents
* Access requires both policy approval and cryptographic validation

Your data remains unreadable without your keys and IronShard's coordination layer.

## Built-In Compliance

IronShard's fragmentation and geo-distribution model aligns naturally with strict regulatory frameworks such as **GDPR, HIPAA, the EU AI Act, and financial-sector requirements**.

**IronShard supports:**

* Provider neutrality
* Automatic versioning
* Multi-region resilience
* AI-ready access control
* Cross-border limitations
* Comprehensive audit logs
* Data residency and jurisdictional boundaries

More secure, resilient, and sovereign data compared to any single cloud provider or AI platform.

### Comprehensive Audit Logs

IronShard records an immutable, complete audit trail for all activity, including:

* Fragment writes
* Access requests
* Reconstruction events
* Administrative changes
* Region placement decisions
* Policy enforcement outcomes
* AI agent interactions and queries

Security and compliance teams gain full visibility into how data is stored, accessed, reconstructed, and consumed, **including by AI systems**.

## FAQs

### What makes IronShard different from traditional multi-cloud storage?

Traditional multi-cloud storage replicates entire files across cloud providers. IronShard uses erasure-coded fragmentation, distributing unreadable fragments across multiple providers and regions. No provider ever sees a full file.

### How does IronShard ensure GDPR compliance?

IronShard keeps encrypted fragments in the regions you specify, enforces geo-fencing, and ensures no provider can reconstruct your data. GDPR-protected data can safely live across cloud vendors without exposing raw content.

### Can organizations control where data lives?

Yes. Region-level and object-level placement rules guarantee data remains inside approved jurisdictions.

### How does multi-provider distribution improve security?

If a provider is compromised, an attacker gains only encrypted fragments. Reconstruction requires fragments from multiple providers and access approval.

### Does geo-distributed storage affect performance?

No. IronShard uses intelligent routing, predictive caching, and access-aware fragment placement to keep latency low, even in multi-cloud configurations.

### Do storage providers have visibility into my data?

No. Providers store encrypted fragments with no usable meaning. Only your organization controls the keys and reconstruction permissions.

---

## GDPR Everywhere

URL: https://www.ironshard.ai/docs/gdpr-everywhere

> GDPR compliance independent of provider or region — encrypted fragments mean no single cloud ever holds a complete, readable file.

# Privacy That Travels With Your Data

IronShard gives organizations **GDPR-grade protection** no matter where their data lives. Instead of relying on the privacy policy of any single cloud provider, IronShard applies a sovereignty layer *above* them. Personal data stays protected, compliant, and unreadable, even when distributed across regions or stored in environments that would normally be off-limits.

## A Cloud Provider-Independent Privacy Model

Every object stored in IronShard is transformed into encrypted fragments and dispersed across multiple storage providers and geographic regions. Each provider holds only a small, encrypted piece, never a complete file. On their own, these fragments reveal nothing and cannot be reconstructed or interpreted.

This design guarantees that:

* No individual provider can ever rebuild a full file, even with full access to their infrastructure.
* No single region or cloud sees raw personal data, removing accidental residency violations.
* Compliance does not depend on where buckets live, IronShard enforces protection independently of the underlying storage.
* GDPR-regulated data can safely span multi-cloud, hybrid, and cross-border architectures, without exposing file contents or breaching local restrictions.

## Data Sovereignty Through Fragmentation

Traditional storage systems tie GDPR compliance to physical location. IronShard flips the model: Compliance comes from how data is stored, not where. Because encrypted fragments are meaningless individually, underlying providers cannot inspect, extract, or infer anything about the file.

This makes it possible to use:

* Global cloud regions
* Mixed cloud providers
* Third-party infrastructure
* Hybrid on-prem \+ cloud setups

…without putting personal or regulated data at risk.

## The Intelligence Layer That Keeps You Compliant

IronShard coordinates access, reconstruction, and policy enforcement through its own secure intelligence layer.

Storage providers remain passive fragment hosts: they never participate in reassembly, governance, or inspection.

The result is a system where:

* Providers only hold encrypted, partial fragments
* IronShard alone orchestrates policies, access decisions, and fragment retrieval
* Data is reconstructed only for authorized users inside the governed environment

This architecture makes IronShard inherently **GDPR-ready everywhere**, even in storage configurations that would normally violate residency or access rules.

## Why This Matters

Organizations can finally modernize their storage strategy (e.g., multi-cloud, global, cost-optimized) without compromising privacy obligations. IronShard ensures that your data stays compliant across:

* Borders
* Providers
* Infrastructures
* Future regulatory shifts

Your data stays yours. Your compliance stays intact. Your storage options stay wide open.

---

## Intelligent Caching

URL: https://www.ironshard.ai/docs/intelligent-caching

> Predictive, geo-aware caching and fragment placement keep hot data near AI agents and compute, with ML-driven pre-positioning for latency-sensitive workloads.

# Intelligent Caching and Geo-Aware Storage for AI-Ready Workloads

IronShard combines advanced caching strategies with geo-aware storage intelligence to deliver low-latency, high-resilience access to distributed datasets. Designed for technical teams managing **multi-cloud or globally distributed workloads**, IronShard ensures speed, reliability, regulatory compliance, and AI-agent readiness.

By integrating **AI-centric optimization** into caching and placement, IronShard makes datasets immediately usable for AI workflows, including retrieval-augmented generation (RAG), model training, and multi-agent pipelines.

## Localized, Adaptive Caching for AI Agents

Each IronShard gateway maintains a **local cache of encrypted object fragments** that adapts dynamically to access patterns. Frequently accessed fragments (or those predicted to be required by AI agents) stay near the relevant compute nodes. Scheduled workloads can pre-load critical data via **cache warm-up requests**, reducing cold reads and latency.

### Key benefits for AI workloads:

* Reduced inter-region traffic and bandwidth costs
* Millisecond-class access for frequently accessed fragments
* Lower latency for globally distributed AI agents and compute nodes
* Immediate discoverability and AI-ready indexing for downstream agents

By caching fragments intelligently, IronShard ensures AI agents can access, process, and infer from data **without delays**, even across global, multi-cloud deployments.

## Adaptive Storage Representation

IronShard continuously monitors **access patterns, workload characteristics, and AI query behavior** to optimize fragment placement, redundancy, and caching across its storage fabric. The system reacts in real time to maintain **cost-efficient, high-performance storage**.

### Standard Class: Reactive Optimization

* Objects start with a baseline redundancy configuration.
* When AI or user access increases, IronShard increases the number of fragments and redistributes them closer to active regions.
* As demand decreases, redundancy returns to baseline, conserving storage and network resources.

This reactive model balances **performance and resource efficiency** for predictable workloads.

### Performance Class: ML-Driven, Proactive Optimization

* IronShard uses machine learning models to forecast future access.
* Models analyze historical access traces, geolocation trends, seasonal patterns, and AI workload activity.
* Fragments are proactively repositioned to the nearest edge or regional gateway to ensure low-latency access.

## Benefits for AI agents:

* High-throughput, globally distributed model training and inference
* Reduced cold-start delays for RAG and agent-driven workloads
* Consistent performance under traffic spikes, eliminating manual tuning

## Technical Advantages

IronShard's intelligent caching and geo-aware architecture delivers:

* **Millisecond access for hot data**: Local caches keep frequently accessed fragments near AI agents.
* **Global low-latency access**: Predictive fragment placement minimizes cross-region retrieval times.
* **Reduced bandwidth and operational costs**: Adaptive caching and redistribution lower inter-region traffic.
* **Self-optimizing storage layer**: Erasure-coded fragments, reactive redundancy, and ML-driven predictions automatically evolve with AI workloads.
* **Regulatory compliance**: Fragmentation and geo-fencing ensure data residency and privacy requirements are met, even in multi-cloud deployments.

## How It Works

1. **Fragmentation**: Data is divided using erasure coding, creating encrypted, redundant fragments across multiple providers and regions.
2. **Reactive redistribution**: Real-time monitoring relocates fragments based on access frequency and AI agent activity.
3. **Proactive placement**: ML-driven predictions pre-position fragments near compute nodes or edge gateways for low-latency AI queries.
4. **Secure access coordination**: Requests are validated against policies; only authorized clients can reconstruct objects.
5. **Audit & monitoring**: Every fragment write, movement, and access by AI or humans is logged for full transparency.

## A Storage Architecture That Evolves With AI Workloads

IronShard combines **erasure-coded redundancy, adaptive placement, and ML-driven performance optimization** to create a storage layer that is:

* **Durable**: Maintains availability in case of multi-provider, multi-region failures.
* **Cost-efficient**: Reduces storage and bandwidth overhead without compromising durability.
* **Globally optimized**: Dynamically adjusts to AI workloads, minimizing latency for distributed agents.
* **Self-optimizing**: Automatically evolves as AI access patterns change, eliminating manual tuning.

Technical teams gain a storage layer that is **resilient, efficient, and optimized for AI workflows** at global scale.

## FAQs

### How does IronShard ensure low-latency access for AI agents?

Local caches and predictive fragment placement keep frequently requested fragments near compute nodes, minimizing round-trip times for AI workflows.

### Can predictive optimization prevent AI performance bottlenecks?

Yes. ML models anticipate spikes in AI query or training workloads and pre-position fragments for uninterrupted throughput.

### Does this system increase storage costs?

No. Adaptive redundancy and proactive caching reduce overall storage and network overhead compared to static replication while maintaining performance.

### How is data security maintained with cached fragments?

All cached fragments remain encrypted in transit and at rest. Only authorized clients with policy-approved access can reconstruct data.

### Is this architecture compatible with multi-cloud and hybrid environments?

Yes. Fragments can be distributed across multiple cloud providers, regions, or on-premises infrastructure while maintaining durability, compliance, and AI-readiness.

---

## Resilience and Adaptive Redundancy

URL: https://www.ironshard.ai/docs/resilience

> Erasure coding across clouds — any k of k+m fragments reconstructs an object, fewer reveal nothing. Durability above triple replication at lower overhead.

# Resilience and Adaptive Redundancy

IronShard replaces traditional replication with an **erasure-coding** designed for **durability, efficiency, multi-cloud resilience, and AI workloads**. Instead of storing full replicas, IronShard divides each object into *k* data slices and generates *k + m* redundant fragments using randomized coefficients. Any *k* fragments can reconstruct the original object, while fewer than *k* fragments reveal no usable information, ensuring full data confidentiality.

This architecture provides a stronger, more efficient foundation for secure, globally distributed storage, **optimized for** **AI and machine learning workloads** that demand high availability, low-latency access, and safe multi-region operations.

## Core Benefits of the Erasure-Coded Model for AI Workloads

### Higher Durability Than Triple Replication
IronShard requires only a subset of all the fragments to reconstruct an object. This means fragment loss, provider outages, or regional failures do not compromise durability.

**AI benefit:** Distributed model training, retrieval-augmented generation (RAG), and multi-agent pipelines can continue uninterrupted even under partial provider or region failures, avoiding bottlenecks in AI workflows.

### Reduced Storage Overhead

Erasure coding achieves **durability comparable to triple replication** while consuming a fraction of the storage footprint.

**AI benefit:** Large AI datasets, including training corpora and preprocessed feature sets, can be stored cost-effectively, reducing overhead for high-volume, high-velocity AI workloads.

### Cloud-Agnostic Fault Tolerance

Fragments are distributed across **regions and multiple cloud providers**, removing single-provider dependency. Data remains recoverable even if an entire provider or region becomes unavailable.

**AI benefit:** Multi-cloud and hybrid AI deployments are supported seamlessly, enabling globally distributed AI agents to access the necessary fragments without interruption.

### Lower Environmental Impact

Fewer redundant bytes stored and transferred reduce energy consumption compared to conventional replication-heavy storage.

**AI benefit:** Energy-efficient storage aligns with sustainable AI practices, reducing the environmental footprint of large-scale model training and inference workloads.

## Why Erasure-Coded Storage Matters for AI

1. **Low-latency reconstruction for AI agents**: Only a subset of fragments is needed, so IronShard can reconstruct objects quickly for ML training, inference, or retrieval-augmented pipelines.

2. **Safe multi-region access**: AI agents can safely query datasets across multiple regions without violating regulatory or compliance policies.

3. **Predictable availability under load**: Distributed fragments ensure that high-demand AI workloads do not experience downtime or data unavailability.

4. **Cost-efficient scalability**: As AI datasets grow, erasure-coded storage minimizes additional storage costs while maintaining durability and fault tolerance.

## Summary

IronShard's **erasure-coded distributed redundancy** provides a storage foundation that is:

* **Durable**: Survives provider outages and regional failures.
* **Efficient**: Minimizes storage overhead compared to traditional replication.
* **Multi-cloud resilient**: Enables fault-tolerant AI workloads across any provider or region.
* **Environmentally responsible**: Reduces energy usage for large-scale AI operations.

For AI teams, this means **highly available, resilient, and cost-effective storage** for training, inference, and multi-agent workflows, without compromising compliance or data security.

---

## Secure Ingest Pipeline

URL: https://www.ironshard.ai/docs/ingest-pipeline

> Every object is compressed, encrypted per-object, erasure-coded, and distributed across providers and regions — the write path that makes data durable and confidential.

# Secure Ingest Pipeline for AI-Ready Storage

IronShard's secure ingest pipeline is engineered to prepare data for **AI workloads, distributed processing, and multi-cloud governance** from the moment it enters the system. Every object moves through a **hardened, multi-stage pipeline** that ensures confidentiality, durability, and efficient downstream access for AI agents and automated workflows.

## Multi-Stage Ingest Flow

Each object entering IronShard follows a deterministic **compress → encrypt → encode → distribute** sequence:

### 1\. Adaptive Compression

Data is compressed using algorithms that optimize for both **throughput and size reduction**.

* Minimized storage footprint
* Reduced network transfer costs
* Quick ingestion for high-volume AI datasets and streaming pipelines

### 2\. Per-Object Encryption

After compression, payloads are protected with **unique per-object encryption keys**.

* Strict end-to-end confidentiality
* Zero-trust and multi-tenant AI architectures
* Encryption key isolation to prevent cross-object exposure

### 3\. Erasure Coding

The encrypted payload is divided into slices and encoded using erasure correction codes to produce redundant, recoverable fragments.

* Stronger durability and lower overhead than replication
* Any valid subset of fragments can reconstruct the object
* Fewer than the required threshold leaks zero usable information

### 4\. Intelligent Multi-Region Distribution

Fragments are distributed across regions and cloud providers based on:

* historical access patterns
* geolocation of similar datasets
* predicted access routes for AI agents and compute clusters

This ensures low-latency access for training, inference, and RAG-style retrieval workloads.

## Built-In Security Through Fragmentation

Because fragments are **encrypted and erasure-coded**, they are:

* Protected at rest and in transit
* Individually meaningless without the reconstruction threshold
* Resilient to provider compromise, region failures, or unauthorized access

This design delivers **cryptographic safety**, **physical distribution**, and **access-policy enforcement** from the first moment data enters the system.

## Optimized for AI Pipelines and Autonomous Agents

The secure ingest pipeline prepares data for AI consumption by:

* Creating lightweight, distributed fragments for faster retrieval
* Enabling multi-region inference without data relocation
* Supporting high-throughput ingest for large training and analytics datasets
* Enforcing strict confidentiality for regulated or sensitive AI workloads
* Aligning with governance requirements for enterprise AI systems

AI agents benefit from **predictable performance**, **safe reconstruction**, and **consistent availability**, even during high-load global operations.

## Summary

IronShard's Secure Ingest Pipeline ensures that every object is:

* **Compressed** for efficiency
* **Encrypted** for confidentiality
* **Erasure-coded** for durability
* **Distributed intelligently** for AI-optimized access

This sequence builds a storage foundation that is secure by default, scalable across clouds, and ready for modern AI and multi-agent workloads.

---

## Branching and Snapshots

URL: https://www.ironshard.ai/docs/branching

> Create isolated, copy-on-write branches of any bucket from point-in-time snapshots — experiment on real data without duplicating objects or touching production.

# Isolated Data Environments Without Copying Your Buckets

IronShard Branching allows technical teams to create **logical, isolated versions of datasets** without duplicating underlying objects. Each branch is based on a **point-in-time snapshot** and diverges using **copy-on-write semantics**, giving you the freedom to experiment, test, or run AI workflows on real data while keeping your production buckets untouched and maintaining full data ownership.

Your original bucket stays pristine, branches evolve independently, and no custody transfer occurs. This approach maximizes flexibility while minimizing storage overhead.

## Why Branching Matters

### Safe Experimentation for ML and AI

Branches provide isolated environments for:

* Model training
* Multi-agent AI workflows
* Preprocessing and data transformation tests
* Retrieval-augmented generation (RAG) pipelines

Everything occurs in a separate branch, so production data remains untouched.

### Simplified Data Governance

Each branch inherits IronShard's security controls, access rules, lineage tracking, and regional restrictions, providing:

* Full auditability
* Consistent governance across every environment

### Instant Parallel Development

Data engineers can safely test:

* Schema changes
* Migration scripts
* Integration pipelines

…without risking the main dataset.

### Reliable Historical Analysis

Branches can be created from previous snapshots to reconstruct how your data appeared at any point in time, enabling:

* Audits
* Debugging
* Root cause analysis

## How IronShard Branching Works

### 1\. Snapshot Creation

IronShard generates a lightweight snapshot capturing the exact state of your bucket at a given point. The snapshot is a metadata-only view, not a full copy of the data.

### 2\. Branch from the Snapshot

Branches reference objects from the snapshot. Until data diverges, reads pull from the parent, eliminating the cost and delay of copying large datasets.

### 3\. Copy-on-Write Semantics

Modifications within a branch are written only to that branch, leaving the original data unchanged. This ensures version isolation with minimal storage growth.

### 4\. High-Performance Indexing and Routing

Branches leverage IronShard’s intelligence layer, providing:

* Region-aware routing
* Low-latency access
* AI-ready indexing for all datasets

### 5\. Governance on Every Branch

Each branch automatically enforces:

* Lineage tracking
* Immutable activity logs
* Controlled sharing rules
* Data residency restrictions
* Encryption and fragmentation policies

Branches are fully compliant without additional configuration.

## Key Benefits of IronShard Branching

* **Instant branching**: Metadata-only creation completes instantly.
* **Cost-efficient storage**: Only changes are stored, eliminating duplication of large datasets.
* **Built for AI workloads**: Branches are fully discoverable and indexable by AI agents while respecting strict access boundaries.
* **Secure and resilient**: Branches use the same encrypted, fragmented storage as the main bucket. No provider can reconstruct data.
* **Full data ownership**: All data can remain in your buckets; IronShard adds intelligence, not custody.

## Developer & AI Workflows

| Team | Use Case | Branching Workflow |
| ----- | ----- | ----- |
| **Data Scientists / ML** | Fine-tune models or test preprocessing | Create a branch from the latest snapshot → preprocess → train → evaluate → discard or merge insights |
| **AI Agents, RAG**  | Isolated environments per task/run | Fork a snapshot per agent → execute → analyze outcomes → delete branch |
| **DevOps / Platform** | Test transformations or schema migrations | Create a branch → run migration scripts → validate → optionally merge or reset |
| **Audit / Compliance** | Reconstruct historical datasets | Branch from a past snapshot → query or inspect the dataset as it existed |

## Getting Started with Branching

1. Enable branching when creating or registering your bucket.
2. Create a snapshot to mark a stable point in time.
3. Fork a branch from the latest state or a selected snapshot.
4. Apply optional policies: retention, protected access, or expiration.
5. Connect pipelines, agents, or test environments to the branch endpoint.
6. Merge insights, retain the branch, or delete it when finished.

Branching on IronShard provides fast, isolated, AI-ready storage environments for technical teams. By combining copy-on-write semantics, lightweight snapshots, and intelligent routing, it enables experimentation, compliance, and multi-cloud resilience without duplicating data or compromising governance.

---

## API Compatibility and Extensibility

URL: https://www.ironshard.ai/docs/api-compatibility

> IronShard implements the AWS S3 API, so existing SDKs, pipelines, and S3 tools connect without code changes — plus metadata and policy extensions for AI workloads.

# API Compatibility and Extensibility

**IronShard delivers full AWS S3 API compatibility**, enabling seamless adoption without rewriting applications, pipelines, or automation. If your tools speak S3, they already speak IronShard.

## 100% S3-Compatible Storage Layer

IronShard's API layer is designed to be a drop-in replacement for any S3-based workflow. Existing SDKs, libraries, and cloud-native services can connect without code changes.

This includes:

* AI data pipelines
* Analytics platforms
* ETL and ELT workflows
* Data lake ingestion systems
* CI/CD and DevOps automation
* Backup and archival processes
* Multi-agent AI runtimes and orchestrators

## Zero Migration Overhead

Because IronShard mirrors the S3 interface, teams benefit from:

* No SDK updates
* No pipeline rewrites
* No workflow disruptions
* Instant compatibility with existing tools

Organizations preserve their current investments while upgrading the underlying storage to a secure, multi-cloud, and AI-ready model.

## AI-Ready Extensibility

IronShard's compatibility extends beyond basic S3 semantics. The platform adds a metadata and policy layer designed specifically for AI agents, retrieval systems, and distributed compute:

* **AI indexability:** IronShard maintains a searchable intelligence layer that AI systems can query safely.
* **Policy-aware access:** AI agents inherit the same access rules as humans, preventing unauthorized reads or cross-tenant leakage.
* **Consistent behavior across clouds:** Agents and pipelines get predictable performance whether data lives in AWS, GCP, Azure, or hybrid environments.
* **Branching & snapshots integration:** Applications can access point-in-time data versions via standard S3 calls, ideal for reproducible AI experiments and deterministic workflows.

This lets ML teams, LLM-based systems, and automation platforms operate on structured, governed, and AI-discoverable datasets without custom integration work.

## Extensible by Design

IronShard enhances S3 compatibility with features that support advanced enterprise needs:

* Custom metadata
* Audit-ready logging and lineage
* Fine-grained access policies and region controls
* Unified access across multi-cloud and hybrid buckets

## Why S3 Compatibility Matters

For modern teams working across clouds and building AI-driven systems, S3 API compatibility ensures:

* Interoperability with existing AI, analytics, and data engineering stacks
* Predictable behavior for distributed agents and batch workloads
* Rapid adoption with zero friction
* Minimal operational overhead
* Broad ecosystem support

IronShard becomes the intelligence layer for your data without becoming a bottleneck or forcing a migration.

## Summary

IronShard provides **full S3 API compatibility** paired with next-generation extensibility, giving organizations a way to modernize their storage layer while keeping every workflow, tool, and AI system running seamlessly.

---

## Storage Classes

URL: https://www.ironshard.ai/docs/storage-classes

> Budget, Standard, and Performance storage classes with adaptive redundancy — flat per-class pricing while placement and protection adjust to how data is used.

# Storage Classes

IronShard offers three **storage classes** that let you choose the balance of **cost, durability, and performance** that best fits your data.  
Each class maintains IronShard's *GDPR-everywhere* guarantee, and all classes use our **adaptive redundancy** system, dynamically adjusting how many copies or encoded fragments of your data exist and where they are placed, based on how often and how quickly you need to access them.

Unlike traditional object storage, where the entire bucket or object must fit a single fixed configuration, IronShard continuously optimizes storage *within* each object at the sub-object (chunk) level.  
That means your data automatically becomes faster when it's hot and more efficient when it's cold, without any manual management or unpredictable pricing.


## Storage Classes Overview

| Storage Class | Data fragments | Redundant fragments | Locality target for hot chunks | Repair priority | Eligible providers/regions |
| :---- | :---- | :---- | :---- | :---- | :---- |
| **Budget** | 4 or 6 | 1-2 (default 1) | none | low | cost-optimized set |
| **Standard** *(default)* | 6 or 8 | 1-4 (default 2) | 4 | medium | broad regional set |
| **Performance** | 6 or 8 | 2-5 (default 3) | 5 | high | full set, including hyperscalers |


### Budget
**For backups, archives, and cold datasets**

The most cost-efficient multi-provider class. Ideal for personal use, proofs-of-concept, or data that is rarely accessed.  
Your data remains safely distributed across independent providers, but redundancy and repair activity are minimized to reduce storage cost.

### Standard *(default)*
**For active projects and general workloads**

A balanced class designed for ongoing workloads, development environments, and content that's frequently accessed but not latency-critical.  
Adaptive redundancy automatically increases protection or locality when your data gets hot, then scales it back as it cools down, all within a predictable flat price.

### Performance
**For analytics, AI, and latency-sensitive data**

Our fastest class, built for compute-intensive and interactive applications.  
Performance class data benefits from **predictive cache warming**, **low-latency locality placement**, and **straggler-smoothing** techniques that minimize tail latency even under load.  
You always get the best possible response times within the SLA, without needing to over-provision or manually move objects between tiers.


## How IronShard's Classes Differ from Traditional Tiers

Conventional object storage systems (like AWS S3 or GCP Storage) use fixed storage classes and optional “intelligent tiering”, moving entire objects between static pools depending on how long they've been idle.  
That approach changes latency and sometimes price when data moves between tiers.

IronShard takes a different path:

- **We don't move objects between pools.**  
  Instead, we adapt redundancy and placement *within* the same class, at the sub-object level.
- **You always pay a flat price per class.**  
  Internal optimizations never affect your bill.
- **You never lose performance suddenly.**  
  Hot regions of your data are proactively accelerated before you notice slowdowns.


### **At a Glance**

| Traditional Tiering | IronShard Storage Classes |
| :-- | :-- |
| Whole-object lifecycle automation (cold objects moved to slower pools). | Continuous, intra-object optimization of redundancy and placement. |
| Fixed redundancy per class. | Adaptive redundancy tuned in real time to your data's activity. |
| Price and latency change when data is moved. | Flat price, steady SLA-grade performance within each class. |

## Why This Matters

- **Predictable pricing:** Each storage class has a fixed logical price per TB. You can choose Budget, Standard, or Performance, and never worry about surprise charges when your data becomes active.  
- **Automatic optimization:** IronShard continuously balances performance and cost behind the scenes, so you always get the right speed and reliability for your data's current usage.  
- **Consistent SLA:** Your data stays within its class SLA for durability and latency, regardless of internal redundancy changes.  
- **Smarter sustainability:** By matching protection to demand, IronShard reduces wasted storage and energy, helping you meet green-IT goals without compromising safety.

## How It Compares

### **Hyperscaler Approach**
> Pick a storage class, we handle redundancy.

In large cloud systems, redundancy is fixed and permanently overbuilt to meet a global SLA.  
Even idle data maintains full replication or erasure coding overhead until a lifecycle policy moves it to a colder, slower, and cheaper pool.

### **IronShard Approach**
> Pick a storage class once, we handle the rest.

We keep redundancy minimal when data is cold and scale it up automatically when it gets hot.  
Each class defines a *range* of redundancy and performance levels, and the system adapts within that range continuously: no object rewriting, no tier migrations, and no billing surprises.

## The Value for You

- **Simple choices:** Budget, Standard, or Performance, just pick what fits your workload.
- **Always right-sized:** Your data's protection and locality adjust automatically to how you use it.
- **No surprise bills:** The price per TB stays fixed inside each class.
- **Better efficiency, faster access:** Hot data streams faster; cold data stays affordable.
- **GDPR-everywhere:** All data, in every class, is stored only in GDPR-compliant regions and providers.

## Choosing the Right Class

Use this quick guide to select the best class for your workload:

| Use Case | Recommended Class | Key Benefits |
| :-- | :-- | :-- |
| **Personal backups, archives, logs, and cold datasets** | **Budget** | Lowest cost per TB, ideal for long-term storage, automatic redundancy scaling. |
| **Development environments, general-purpose apps, active project data** | **Standard** *(default)* | Balanced cost and performance, adaptive optimization for frequently accessed data. |
| **AI, analytics, real-time processing, low-latency applications** | **Performance** | Predictive cache warming, best tail latency, optimized for compute proximity. |

> **Tip:** You can always change the storage class later through lifecycle rules: IronShard will rebalance your data automatically without downtime.

IronShard gives you the simplicity of storage classes like AWS or GCP, but inside, it adapts automatically, so you always get the SLA you paid for, at lower cost and faster tail latency.