> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-coustics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to deploy the SDK

> Prepare model files, credentials, network access and runtime checks for a production deployment.

Start with a working [SDK](/models/get-started/sdk-quickstart), [LiveKit](/models/get-started/livekit-quickstart) or [Pipecat](/models/get-started/pipecat-quickstart) integration and pin its dependencies.

This guide covers the native SDK. Use the [WebAssembly guide](/reference/sdk/language-bindings/wasm) for browser-specific package and authentication requirements.

## Prepare the release

1. **Pin the version set.** Record the language binding, core SDK, framework plugin and model ID in your release. Keep the lockfile and check the [compatibility matrix](/reference/sdk/compatibility-matrix).
2. **Match the platform.** Select the package or native library for the target OS and CPU architecture. Test library loading inside the deployment image or host environment.
3. **Provision model files.** Download compatible `.aicmodel` files before deployment. Verify the service can read and load them, and retain the exact files with the release.
4. **Inject credentials at runtime.** Follow the [authentication guide](/models/get-started/authenticate-apps) with your secret manager. Keep keys out of images, build arguments, source control and logs.
5. **Retain a rollback bundle.** Keep the previous application, dependencies, models and configuration together so rollback restores a compatible combination.

## Configure network access

Audio inference runs locally through [AirTen](/reference/concepts/airten). Review each network activity separately:

```mermaid theme={null}
flowchart TB
  subgraph host["Your application host"]
    Input["Input audio"] --> SDK["SDK and local model"]
    SDK --> Output["Processed audio or analysis results"]
    Files["Provisioned model files"] --> SDK
  end
  Provision["Package and model distribution"] -. "Provisioning downloads" .-> Files
  SDK -. "Activation and usage metadata, per entitlement" .-> Service["ai-coustics services"]
  SDK -. "Optional error reports" .-> Errors["Error reporting service"]
  SDK -. "Configured metrics" .-> Collector["Your OpenTelemetry collector"]
```

Solid arrows show local processing; dotted arrows show downloads or metadata traffic. SDK inference does not upload input audio. Your application and downstream services may have separate audio flows. Entitlements and telemetry settings determine which network paths apply.

| Activity                               | Deployment check                                                                                                                       |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| **Package and model download**         | Allow access in the provisioning environment, or distribute the validated artifacts through your own deployment system.                |
| **SDK activation and usage reporting** | Verify connectivity under the deployed credential and entitlement. Test rejection and connectivity loss, as well as normal activation. |
| **Client token issuance**              | Keep the long-lived key on your backend. Test token retrieval, expiry and refresh from the client environment.                         |
| **SDK error reporting**                | Decide whether to use it; set `DO_NOT_TRACK=1` before SDK loading if disabled.                                                         |
| **Customer OpenTelemetry export**      | Configure the collector endpoint and authentication separately. Verify network access from the application container or host.          |
| **Framework and downstream services**  | Review LiveKit, speech-to-text and other application dependencies independently.                                                       |

See [telemetry](/reference/concepts/sdk-telemetry) for data categories and controls. For restricted egress, obtain the current destination requirements from ai-coustics.

Disconnected deployment requires a suitable offline license and provisioned models. Test a cold start and the required operating period under your network restrictions, including entitlement expiry or renewal. An online session tolerating a network failure does not establish offline support.

## Separate startup from audio processing

Create and initialize models, processors and voice activity detection (VAD) instances before accepting live audio. Keep downloads, credential retrieval, initialization and teardown outside real-time audio callbacks.

Allocate an independent processor and VAD state for each independent stream. Process frames in order and follow the [streams and state](/reference/concepts/streams-and-state) guidance for reset, reconnect and concurrency. Match the sample rate, mono format and block size to the actual incoming stream using the [audio format reference](/reference/concepts/audio-format).

Check readiness before accepting traffic:

* **Load the deployed model.** Verify the file path and compatibility with the installed core SDK.
* **Check a controlled audio fixture.** Process a non-silent recording with valid authorization, inspect errors and verify output length, format and expected processing behavior.
* **Check framework activation.** Confirm the filter is active and not silently passing audio through.
* **Measure under load.** Exercise the expected stream count under the deployed CPU and memory limits.

Use controlled fixtures for readiness tests and keep production audio out of diagnostics and CI artifacts.

## Set a capacity and failure policy

A 160-sample frame at 16 kHz represents 10 ms of audio. Sustained processing above 10 ms cannot keep pace on a serial path. Compare frame processing time against this budget.

Record high-percentile processing time, queue depth, memory and CPU use at the intended concurrency. Include resampling and framework overhead. Use the [performance guide](/reference/concepts/performance) and [OpenTelemetry metrics](/models/get-started/opentelemetry) to track regressions.

Bound queues and choose an overload policy: reject new sessions, stop the failing session or report a fallback. Test CPU throttling, credential rejection and token-refresh failure. Surface background-task errors.

Report bypass and degraded processing separately from active enhancement, VAD or analysis.

## Shut down and upgrade

Stop new streams and audio submissions, finish or cancel pending work and release SDK instances outside the audio callback. Stop token-refresh tasks too.

Where exposed, `terminate_session()` requests termination and can block during cleanup. Processing may be disabled after it returns; submit no further frames and create a new instance for a new session.

Before upgrading, compare the same fixtures, failure cases and settings on both versions. Check the [changelog](/changelog), [compatibility matrix](/reference/sdk/compatibility-matrix) and applicable migrations, then roll out gradually.

## Verify the deployment

Record these results with the release:

| Check                 | Evidence to retain                                                                          |
| :-------------------- | :------------------------------------------------------------------------------------------ |
| **Cold start**        | Package/core/model versions, target OS/architecture and successful model loading            |
| **Active processing** | Controlled input, checked SDK return path and inspected output                              |
| **Session isolation** | Independent streams, reset/reconnect behavior and clean shutdown                            |
| **Capacity**          | Hardware/resource limits, stream count, processing-duration distribution and queue behavior |
| **Failure recovery**  | Rejected credential, token expiry/refresh, lost connectivity and overload behavior          |
| **Observability**     | Sanitized error record and confirmed metrics in the intended collector                      |
| **Rollback**          | Successful rerun using the retained previous release bundle                                 |

Use [troubleshooting](/production/troubleshooting) for failed checks. See your agreement and [pricing and support information](/models/get-started/pricing) for commercial terms.