Production Setup

Use this guide when a local MeshKit proof of concept needs to become a production storage path.

Production setup is not just replacing LocalDevProvider. You must decide where encrypted bytes, MeshKit metadata, retrieval, policy decisions, persistence proofs, logs, and secrets live.

Step 1: Choose The Provider Boundary

Boundary	Question to answer
Byte storage	Where do encrypted envelope bytes and stream chunks live?
Metadata service	Where do proofs, capsules, mailboxes, sync jobs, vaults, capabilities, and logs live?
Retrieval	Which provider or gateway reads bytes back by CID?
Identity directory	How are recipient public keys published and resolved?
Policy	Are share opens gated by an external policy service?
Persistence	Do stored CIDs need Filecoin or other long-term retention evidence?
Observability	Which doctor checks, logs, and validation outputs are retained?

Step 2: Create `meshkit.config.json`

{
  "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
  }
}

Use tokenEnv in files committed to source control. Resolve secrets from the environment or a secret manager at runtime.

Step 3: Load Config In Application Code

import { meshkit } from "@meshkit/meshkit";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing required environment variable ${name}`);
  }
  return value;
}

const mk = await meshkit.fromConfig({
  version: 1,
  appId: "mk_production_app",
  provider: {
    type: "ipfs-http",
    ipfsApiUrl: requiredEnv("MESHKIT_IPFS_API"),
    metadataApiUrl: requiredEnv("MESHKIT_METADATA_API"),
    token: process.env.MESHKIT_PROVIDER_TOKEN,
    timeoutMs: 15000,
    retries: 2,
  },
});

Do not print full environment objects or config files that may contain inline tokens.

Step 4: Add Optional Services

Filecoin persistence and policy providers are separate from storage:

{
  "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"
  },
  "persistence": {
    "type": "filecoin-http",
    "endpoint": "https://filecoin.internal.example",
    "tokenEnv": "MESHKIT_FILECOIN_TOKEN"
  },
  "policy": {
    "type": "lit-http",
    "endpoint": "https://policy.internal.example",
    "tokenEnv": "MESHKIT_POLICY_TOKEN"
  }
}

The Filecoin provider is an HTTP bridge boundary. It does not configure wallets, Boost, Lotus, storage provider allowlists, pricing rules, retrieval policy, or renewal automation inside the SDK.

The Lit-compatible policy provider is an HTTP authorization boundary. If it is unavailable, policy-backed opens fail closed instead of decrypting from stale policy state.

Step 5: Validate Evidence

Run diagnostics from the same environment that will run the app:

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

Validation should prove the workflows you ship:

write encrypted bytes
read by CID
verify proof metadata
create/open/revoke a capsule if sharing is enabled
enqueue/read mailbox records if messages are enabled
enqueue/flush sync jobs if offline work is enabled
call policy and persistence providers if configured
redact tokens and plaintext from logs

Skipped live-provider scripts are not evidence.

Redaction Rules

Never include these in logs, support bundles, examples, or issue reports:

provider tokens
authorization headers
bearer tokens
cookies
API keys
private keys or seed material
.npmrc content
decrypted content
capability token secrets
full provider response bodies that may include credentials

Safe to include:

environment variable names
CID
provider name
proof summary
capsule ID
deal ID
policy ID
sanitized MeshKitError.code and suggestion

Common Production Failures

Symptom	Likely cause	Action
Write succeeds but read fails	Byte store and metadata service are not aligned	Confirm both point to the same environment and tenant
Browser app cannot use Kubo	App connects directly to unrestricted Kubo RPC	Put Kubo behind a trusted service boundary or use an app-owned runtime path
Share opens locally but not in production	Capsule or recipient identity metadata is missing	Validate metadata service and identity directory
Filecoin deal active but retrieval fails	Deal state is not retrieval evidence	Validate retrieval through gateway, bridge, or provider path
Policy-backed share fails closed	Policy provider unavailable or denies access	Restore policy service or update membership