Deployment Overview
This page walks through the high-level deployment process and helps you choose the right deployment model for your infrastructure.
Deployment Steps
Regardless of the deployment model, every installation follows these steps:
Get the container image
Authenticate with the registry and pull the image. See the Container Image guide.
Choose a deployment model
Select the platform that matches your infrastructure. See the options below.
Configure and deploy
Follow the platform-specific deployment guide to run the engine.
Verify the service
Confirm the engine is healthy and responding to requests. See Verification & Testing.
Secure the deployment
Apply network policies and security best practices. See Security.
Choosing a Deployment Model
Kubernetes-based
Best for production workloads that need horizontal scaling, rolling updates, and self-healing. The Hiya engine is stateless and scales by simply increasing the replica count.
Managed Container Services
Suitable when you want the cloud provider to manage the underlying compute or when Kubernetes is not part of your stack.
Single Host
Best for development, testing, or low-traffic deployments on a single machine.
Common Configuration
All deployment models share these configuration parameters:
Environment Variables
These environment variables are required to start the container service unless a platform-specific guide explicitly states otherwise.
| Variable | Required | Default | Description |
|---|---|---|---|
API_KEY | Yes | — | API key used for usage metering. Create one with Create a key or copy it from the Audio Intel keys UI. |
ORG_HANDLE | Yes | — | Your organization handle. Get it from List your organizations or from your organization page in the Hiya UI. |
PLATFORM_REGION | Yes | — | Set to eu or us. This must match the region you use to log in to the Hiya platform. |
MIN_ALLOCATION | Yes | — | Initial allocation bag of minutes consumed by the container. Each hiya-voice-verification container reserves this amount at startup, then requests more as usage depletes it. Recommended values are PT1M or PT5M. |
PORT | No | 8080 | Health check port (gRPC health protocol). |
WS_PORT | No | 8081 | WebSocket API port. |
Model Storage
At startup, the engine loads ML models into the path /opt/loccus/models. This path should be backed by a RAM-based filesystem (tmpfs, emptyDir with medium: Memory, or equivalent) of at least 8 GiB so that model data is held in memory and never written to persistent disk.
Network Requirements
| Direction | Destination | Port | Protocol | Purpose |
|---|---|---|---|---|
| Outbound | api.hiya.com | 443 | HTTPS | License verification and billing |
| Inbound | Engine container | 8080 | gRPC | Health checks |
| Inbound | Engine container | 8081 | WebSocket | Voice verification API |
Using the Service
The self-hosted engine exposes the same API interface as the Hiya cloud service. This means you can:
- Develop and test your integration against the cloud API at
wss://api.hiya.com/audiointel/... - Deploy the self-hosted engine using one of the guides above
- Switch your client to point at the self-hosted endpoint by changing the host and port
The engine supports the same WebSocket streaming endpoint. The only difference is the destination — instead of api.hiya.com, you point to your self-hosted engine's address (e.g., ws://your-engine-host:8081).
We recommend developing your integration against the cloud API first, then switching to self-hosted once your deployment is verified. This lets you validate your client code independently of infrastructure setup.