Skip to content

0.6 prerelease checklist: stabilize guest-agent API and SDKs #1094

Description

@h4x3rotab

Objective

Ship dstack 0.6 with a stable, versioned guest-agent API and consistent Go, JavaScript/TypeScript, Python, and Rust SDKs. Existing 0.5.x clients must continue to work against a 0.6 agent.

Compatibility

  • Keep the unversioned API fully compatible with 0.5.x, verified with v0.5.10 generated clients and SDKs. — ci(sdk): run released 0.5.x SDK suites against the current agent #1121 runs the released SDK suites against the current agent in CI. The pinned tags are v0.5.8 and v0.5.11, not v0.5.10: v0.5.10:sdk and v0.5.11:sdk are the same tree object, so running both bought nothing. Note the limit — old JSON clients ignore unknown keys, so this job catches breaking changes to the frozen surface but not additive ones; the shape freeze in frozen_surface is what covers additions.
  • Keep GetQuote unchanged: the v0.5 response fields and semantics remain the complete contract. Cross-platform attestation is exposed through Attest, not GetQuote.
  • Keep GetKey wire- and behavior-compatible. Publish a normative specification for path, purpose, supported algorithms, defaults, output encoding, and signature-chain verification. — spec in docs: give the frozen v0 guest API a written contract #1123 (docs/guest-api-v0.md), byte-level: HKDF salt, what enters the KDF vs only the claim, both chain-link preimages, all three signing modes, and the hazard that algorithm does not domain-separate.
  • Make EmitEvent return 404 with informative error message (deprecated method)
  • Unknown algorithms must be rejected.

Attestation

  • Make Attest the single API for platform and GPU attestation

SDKs

Versioned API (future)

  • Introduce the long-term API under a versioned URL/service namespace such as /prpc/v1/... and protobuf package dstack.guest.v1. API selection must not depend on request headers. — guest-agent: freeze the v0 API at v0.5.11 and add the versioned v1 API #1116; selection is by URL path alone.
  • Use *Request and *Response consistently for new messages. Keep the method name Attest.
  • Give opaque JSON fields explicit *_json names in v1, or use typed messages where the schema is stable. — not done. InfoResponse still carries app_compose, vm_config and key_provider_info as bare string fields whose comments say they are JSON documents passed through unparsed. v1 is unreleased, so this is still cheap to change.

Signing (future)

  • Provide Sign with an explicit key specification containing path, purpose, and algorithm. — v1 has no Sign; the frozen v0 Sign is now specified in docs/guest-api-v0.md.
  • Add GetSigningKey to return the corresponding public key and certification chain without signing a message. — v1 GetKey returns public_key and signature_chain alongside the key, which covers the use case but not as a separate method.
  • Provide signature verification as SDK functionality rather than an agent RPC. — refactor!: move signature verification out of the CVM and into the SDKs #1110. v0's Verify RPC is still served for 0.5.x clients and is documented as frozen.
  • Specify the exact Ed25519 and secp256k1 message and prehashed modes. — done for the frozen v0 surface in docs: give the frozen v0 guest API a written contract #1123, including secp256k1_prehashed requiring the caller to supply the digest. v1 has no signing surface to specify.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions