SDK

The SDK facade is the default path for application code. It gives you one import, local development defaults, and the same typed client namespaces that Core assembles behind the scenes.

Use the SDK when you want to build product features: encrypted file storage, structured records, sharing, messages, streaming, sync, and basic diagnostics. Move to Core when you need to construct providers, wire runtime-specific capabilities, customize identity directories, or integrate telemetry and policy infrastructure.

Install First

npm install @meshkit/meshkit

Do not install or import an unscoped meshkit package. The application facade is @meshkit/meshkit.

Minimal Client

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

export async function createAppStorage() {
  return meshkit({
    identity: "app-device",
  });
}

With no provider option, MeshKit uses the local development provider. That is the right default for tutorials and tests, but it is not durable production storage.

What You Can Build With The Facade

Namespace	Use it for	Keep in your app database
`files`	Store, read, and stream encrypted binary or text content	CID, content type, proof summary
`records`	Store encrypted structured app records	CID or record ID, schema/version metadata
`share`	Create and open capsules for recipient identities	Capsule ID, recipient identity, expiry/revocation state
`messages`	Send encrypted mailbox-style messages	Message ID, thread or mailbox identifiers
`sync`	Queue and inspect sync work	Sync job ID, retry state
`doctor`	Check client/provider health	Health report and failing checks

The facade also exposes advanced namespaces from Core, including policies, vaults, capabilities, persistence, CAR, observability, retrieval, interop, AI, agent, proofs, and providers. Treat those as advanced workflows unless your feature needs them immediately.

First Useful Workflow

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

const mesh = await meshkit({ identity: "demo-device" });

const saved = await mesh.files.put("welcome.txt", "Private app data", {
  contentType: "text/plain",
});

const opened = await mesh.files.get(saved.cid);

console.log({
  cid: saved.cid,
  provider: saved.proof.provider,
  encrypted: saved.encrypted,
  text: await opened.text(),
});

The CID identifies encrypted MeshKit envelope bytes. Store it if your app needs to retrieve, share, audit, or persist that content later.

When To Leave The SDK Facade

Use Core or a runtime package when:

You are replacing local-dev with Kubo, Helia, pinning, gateway retrieval, Filecoin, policy, or fallback providers.
You need browser, Node, React Native, or Ionic capability detection.
You need a custom identity directory, proof adapter, telemetry sink, persistence provider, or policy provider.
You are implementing infrastructure rather than an application feature.

Production Boundary

Before production, decide where these responsibilities live:

Encrypted bytes
MeshKit metadata for proofs, capsules, mailboxes, sync jobs, vaults, capabilities, and logs
Retrieval gateway or provider
Policy decisions and capability checks
Persistence proofs such as Filecoin deal state
Operational validation and audit evidence

Then move provider construction into a Core-facing infrastructure module or meshkit.config.json.

Next Steps

New project: Install
First round trip: SDK Quickstart
Store content: Files
Store structured data: Records
Share access: Sharing
Production setup: Provider setup