Providers

Providers decide where encrypted bytes and MeshKit workflow metadata live. Choose them by workflow, not by infrastructure preference alone.

The SDK facade is enough for local development. Provider pages are for the moment you need production storage, retrieval, pinning, policy, persistence, failover, or validation evidence.

Provider Decision Table

Need	Start with	Notes
Tutorial or deterministic test	Local dev	Not durable production storage
Kubo-compatible IPFS HTTP API	IPFS HTTP / Kubo	Requires MeshKit metadata service beside Kubo
App-owned in-process IPFS	Helia	App owns Helia/libp2p setup
Pin lifecycle	Pinning service	Pinning does not replace backing storage and metadata
Gateway read path	Gateway retrieval	Verify bytes against CID before decrypting
Private operator cluster	IPFS Cluster	Cluster REST is not Kubo RPC
Ordered failover	Fallback	Useful only when metadata boundaries are compatible
Long-term retention proof	Filecoin	HTTP bridge abstraction, not direct Filecoin client
External access decisions	Lit policy	HTTP policy boundary; fail closed when unavailable

The Production Rule

Production MeshKit needs both:

encrypted byte storage
+ MeshKit metadata service

The metadata service stores proofs, capsules, revoked capsule state, mailbox records, sync jobs, vaults, capabilities, logs, and health checks. A stock IPFS node or gateway is not enough for workflows that need those records.

Configuration Shape

Most production deployments centralize provider config:

{
  "version": 1,
  "appId": "mk_production_app",
  "provider": {
    "type": "ipfs-http",
    "ipfsApiUrl": "https://ipfs-api.internal.example",
    "metadataApiUrl": "https://meshkit-metadata.internal.example",
    "tokenEnv": "MESHKIT_PROVIDER_TOKEN",
    "timeoutMs": 15000,
    "retries": 2
  }
}

Application code can load resolved secrets with meshkit.fromConfig; CLI config should prefer tokenEnv so credentials stay outside the file.

Validation Before Production

Run at least one end-to-end write/read/proof validation against the same provider boundary your app will use:

npx -p @meshkit/cli meshkit doctor --json
npx -p @meshkit/cli meshkit providers test --json

For repository live-provider validation, run the opt-in scripts only after setting the required environment variables.

Common Provider Mistakes

Calling local-dev production-ready because the SDK quickstart passed.
Pointing browser or mobile clients directly at unrestricted Kubo RPC.
Configuring a byte provider without a MeshKit metadata service.
Assuming gateway retrieval proves authorization.
Treating Filecoin deal state as a retrieval guarantee.
Reusing the same bearer token across storage, metadata, pinning, gateway, and policy services.

Next Steps

First migration path: Production setup
Mental model: Provider model
Metadata boundary: Metadata service
Terminal validation: Provider testing