Guides
Guides
Walkthroughs that build a complete app, how-tos for one job, and deep dives on SDK behavior — grouped so you can tell which is which.
This section mixes three kinds of page. A walkthrough builds a complete app from an empty directory; a how-to gets one job done and assumes a working session; a deep dive explains behavior the SDK handles for you, for when you need to reason about it.
Walkthroughs
Start-to-finish tutorials — each ends with a running app you built yourself.
| Guide | You build |
|---|---|
| Build a voice React app | A Vite + React browser app: provider, mic toggle, transcript pane, tool call display |
| Build a Python voice CLI | A terminal voice client on the OS mic and speaker, with clean Ctrl-C teardown |
| Build a Swift Mac CLI | A SwiftPM executable with one typed event stream and graceful shutdown |
How-tos
One job each, for a session you already have.
| Guide | The job |
|---|---|
| Handle tool calls | Observe the tool lifecycle and render a call timeline |
| Add production guardrails | Scrub and classify tool arguments, audit every outcome, gate the end of the call |
| Server tools | Opt into tools that run on Cosmo's backend instead of your process |
| Share your app | Put your app on a public URL with server-side minting and spend limits |
| Packaging a macOS app | Embed frameworks, sign, and add the entitlements swift build alone doesn't |
| Debugging | Correlate session and tool-call IDs to trace a session end-to-end |
Deep dives
Explanations of behavior the SDK already handles — read when you need the why.
| Guide | Explains |
|---|---|
| Reconnects | How the server rotates upstream model sessions without ending yours |
| Envelope chunking | How oversized control messages are split and reassembled |
| Swift platform behavior | What the SDK does to the audio device on macOS and iOS, and what your app still owns |