Nimbus SDK

The MIT-licensed, dependency-free authoring contract for Nimbus connectors and extensions.

The contract is defined once, language-neutrally, in spec/. Each SDK below is a binding of that contract and is held to the same conformance suite.

SDK	Package	Requires	Status
TypeScript	@nimbus-dev/sdk	Node ≥ 22, ESM	Reference implementation
Python	nimbus-dev-sdk	Python ≥ 3.11	Official
Go	github.com/nimbus-agent/nimbus-sdk/sdks/go	Go ≥ 1.26	Official

Each publishes with the strongest provenance its ecosystem supports: npm with --provenance, PyPI with PEP 740 attestations, both via GitHub OIDC with no long-lived token. Go's answer is different in kind rather than weaker — it has no registry and no publish credential at all: a tag is the release, and what protects a consumer there is sum.golang.org, the checksum transparency log every go client verifies automatically. See Releasing.

The Go binding is the newest. It publishes the same capabilities Python does, so the two are narrower than TypeScript by the same set of modules (the rows of the stability matrix showing — for both). Go executes exactly the corpora Python claims — every case of every one of them, nothing deferred — which is every published corpus its surface publishes. Python matches it case for case again as of RFC-0020's S3, which gave nimbus_sdk.signing a from-scratch Ed25519 and retired the one gap between them, manifest-signature's three crypto kinds. Which corpus each binding claims, and the case counts behind it, is generated into docs/conformance-coverage.md rather than restated here. RFC-0012 records its layout, tag format and release model; RFC-0013 promotes it to official, names its owner, and pins what "the full conformance suite" means in GOVERNANCE.md's criterion 1.

Scaffold a connector

A third package, @nimbus-dev/create-connector, generates a connector that handshakes and then serves MCP, in either language:

npm create @nimbus-dev/connector@latest my-connector                  # TypeScript
npx @nimbus-dev/create-connector@latest my-connector --lang python    # Python

The Python line is npx, not npm create, on purpose: npm create parses npm's own options first, so a --lang passed without a -- separator is silently swallowed and you get a TypeScript project with no error. Walk through either output — and understand what you got — with the TypeScript or Python quickstart. CI generates, installs, builds, tests and drives that output as a process on every run.

The org ships a second scaffolder, create-nimbus-connector, and the two do different jobs: this one templates a greenfield project you then write by hand, and is the only one that emits Python; that one turns a small JSON spec into a connector in the shape the first-party Nimbus connectors already share, and is the one to reach for when wrapping a REST API. Converging them is the stated direction, gated on four preconditions — neither is deprecated.

Supported versions

The declared floors — engines.node, requires-python, and go.mod's go directive — are stability-matrix.md's Runtime support section, generated from the packages themselves; that section owns the floors and they are not restated here. What CI actually tests is a separate claim the generator cannot make — it is not read from any package — so it is recorded here instead, across Linux, macOS and Windows:

• Node 22 and 24 — an ESM smoke test that imports the published entry points. macOS runs Node 24 only.
• Python 3.11, 3.12, 3.13 and 3.14 on Linux. macOS and Windows run the floor and the newest, 3.11 and 3.14.
• Go 1.26 and 1.27 — the two most recent stable minors, which is Go's own support policy. macOS runs 1.27 only. The go directive names the older of the two on purpose; see sdks/go/README.md.

This is not duplication: the matrix section is generated and pins the declared floor value each package ships; this list is hand-maintained and pins the versions CI's matrix jobs actually run, per OS — which, for TypeScript and Go, does not include the floor on every OS (macOS runs each of those two on its newest supported version only). A pull request runs only the jobs its changed paths reach; a push to main runs them all.

The TypeScript package is ESM-only ("type": "module"); there is no CommonJS build. It ships its own .d.ts and declares no minimum TypeScript language version — if you need one guaranteed, open an issue rather than inferring it from the current build.

Dropping a runtime version is a breaking change and follows the deprecation policy, which records why the Node 20 → 22 move shipped as a minor rather than a major.

Modules

Start with server.md and types.md — the contract itself — then reach for a battery as you need it. Every public export of every exports entry point is documented on one of these pages. A guard (sdks/typescript/scripts/docs-coverage.test.ts) fails CI if that stops being true.

Module	What it is
server	NimbusExtensionServer — the connector entry point
types	ExtensionManifest, NimbusItem — the core contract shapes
contract-version	Contract-version negotiation — the majors, the algorithm
item-types	The item-type vocabulary and its guards
agents	Agent briefs, their guards, and the guard factory
audit-logger	The scoped audit logger
hitl-request	Human-in-the-loop request shapes
crypto	JWTs and service-account tokens, plus the original Ed25519 manifest signing, deprecated in favour of signing
icalendar	RFC 5545 building and parsing
jmap-fastmail	Headers, attachment metadata, capped preview
data-profile	CSV / JSON / Parquet structural profiling
flux-cd	Flux CD kind registry
storybook	Storybook helpers
distribution-channel	Channel resolution
ipc	NDJSON line reading and IPC framing
testing	MockGateway, contract tests, the sandbox probe
connector-kit	Dependency-free MCP connector helpers: Zod tool registration, Bearer-auth REST fetch
diagnostics	The structured, redaction-safe diagnostic and audit envelope
signing	Deterministic manifest canonicalization, and the pure half of the detached JWS envelope
manifest-signature	Signing, verifying and key generation for the detached JWS envelope

Examples

• tools/create-connector/templates/ — the smallest connector that handshakes and serves, in both languages. Generate it with the quickstarts rather than copying it by hand.
• sdks/typescript/examples/calendar-connector/ — HITL gating, the audit logger, and the icalendar battery building the VEVENT an approver is shown.

Policies and process

• Roadmap · Architecture · Glossary
• Inclusion policy — the bar a new battery must clear
• Deprecation policy — how an export is retired
• Governance · Releasing · Security
• Contributing — and Discussions, where questions are asked, on the Nimbus board
• Stability and support matrix — every capability crossed with every binding's stability tier, plus binding status and runtime support floors, in one place
• API surface — the generated snapshot of every public export
• Python API surface — the same, for every name in all nine nimbus_sdk import roots
• Go API surface — the same, for every exported declaration in all ten Go packages
• Contract spec — versioned JSON Schemas, the manifest rule registry, the NDJSON wire spec, and the conformance corpora every language binding validates against
• RFCs — contract changes, with the compatibility impact and rationale that produced them

License

MIT — see LICENSE.