SDKs planned

Official client libraries are on the way, and this page explains exactly how they will be made — because the pipeline is the promise. Everything on this portal follows one discipline: references are generated from machine contracts, so they cannot drift from what ships. The configuration reference already works this way (generated from the daemon's own schema). The SDKs extend that discipline literally: the daemon will emit its own API contract, and every client is generated from it.

The pipeline

One contract, emitted at the source, mechanically expanded — no hand-authored spec drifting away from the server, and no SDK that documents an API the daemon doesn't actually speak.

Languages

Scope of the first cut

• Typed models for every wire shape — the stats snapshot, health checks, journal entries with the stable event codes as enums (link.down as a type, never a string), netcheck, the QoS policy document, apply-lifecycle states — and the configuration file itself, generated from the same schema behind the configuration reference, so configs can be built and validated programmatically.
• An HTTP client with the API's real semantics — the ?interface= convention, timeouts, retry-with-backoff on idempotent reads, and TLS options for nodes serving self-signed certificates (custom CA, pinning).
• Authentication, handled — bearer API tokens; the time-windowed mesh node-token via a pluggable token provider (so the mesh secret never has to pass through the SDK's hands); the CSRF header applied automatically on writes.
• Typed errors — the API's stable error codes (validation_failed with its findings array, empty_canary_set, rollout_in_flight, …) surfaced as structured errors, never string matching.
• Ergonomic flows — where an SDK earns its keep over raw codegen: an apply_config() that wraps the whole stage → commit → confirm lifecycle with revert awareness; journal tailing as an iterator with cursor paging handled; wait_healthy(); fleet fan-out helpers.
• A mock daemon in the box — spec-generated test doubles and recorded fixtures, contract-checked against the same OpenAPI document as the real server, so integration code runs in CI with no daemon, no TUN device, no elevated privileges. And because the binary itself is gated, this doubles as the evaluation path: write and test your integration while your access request is still in review.
• Observability of the SDK itself — OpenTelemetry span hooks around every call, structured logging hooks, and a client-generated correlation ID attached to each attempt and surfaced in errors and spans. All of it opt-in interfaces rather than bundled dependencies, so the client stays thin when you don't use them.
• A version handshake — on first contact the client reads the version the daemon's health endpoint already reports and warns when it falls outside the SDK's supported range. Fleets drift; we have watched version skew degrade links silently on our own test fleet, and the SDK should say so before your integration finds out the hard way.

Deliberately out of the first cut: browser/session authentication (that surface belongs to the dashboard) and the hosted console's enrolment APIs. Both are documented decisions, not omissions.

How the SDKs ship

A client library is something you install into your build — for our audience, how it ships matters as much as what it does.

• Signed, attested packages — every SDK release signed under the same verification story as every other Atlas artifact (verify a release), with an SBOM and build-provenance attestation published per release, and a deliberately thin dependency tree. Auditing the package should take minutes, not a sprint.
• Semantic versioning with a stated deprecation policy — breaking changes only in major versions; deprecations announced in a minor and carried for a stated window before removal; and the changelog generated from the OpenAPI diff between releases — the same diff CI uses to block accidental breaks, so the changelog cannot under-report what changed.

The stable surfaces you can build on today

Until the OpenAPI document lands, these are the machine contracts the SDKs will formalize — all stable, all documented, all usable now:

• The config schema — atlasd config schema or GET /api/config/schema: a draft-07 JSON Schema generated from the daemon's own structs. Validate and author configs programmatically today.
• The stats snapshot — GET /api/stats, and the same document at /tmp/atlas/<iface>.json rewritten every second. Shape shown, verified, on the API page.
• The journal's stable codes — machine identifiers that survive upgrades; build against code, never the message. Documented here.
• Prometheus metrics — GET /metrics, base units and disciplined labels, on by default. Scrape config and starter alerts.