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:

1

Get the container image

Authenticate with the registry and pull the image. See the Container Image guide.

2

Choose a deployment model

Select the platform that matches your infrastructure. See the options below.

3

Configure and deploy

Follow the platform-specific deployment guide to run the engine.

4

Verify the service

Confirm the engine is healthy and responding to gRPC requests. See Monitoring & Logging.

5

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.

Kubernetes (any provider)

Provider-agnostic guide for any conformant K8s cluster, including on-prem.

AWS EKS

Amazon Elastic Kubernetes Service with recommended instance families.

GCP GKE

Google Kubernetes Engine with Workload Identity and Autopilot options.

Azure AKS

Azure Kubernetes Service with recommended VM series.

Managed Container Services

Suitable when you want the cloud provider to manage the underlying compute or when Kubernetes is not part of your stack.

AWS ECS

Amazon Elastic Container Service with Fargate or EC2 launch types.

GCP Cloud Run

Google Cloud Run for serverless container deployments.

Single Host

Best for development, testing, or low-traffic deployments on a single machine.

Docker (single host)

Run the engine directly with Docker or Docker Compose.

Common Configuration

All deployment models share these configuration parameters:

Environment Variables

Variable	Required	Default	Description
API_KEY	Yes	—	Provided by Hiya. Used for usage metering.
ORG_HANDLE	Yes	—	Your organization handle. See List your organizations.
PORT	No	8080	gRPC API port.
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) 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	Voice verification API
Inbound	Engine container	8081	WebSocket	WebSocket API

Using the Service

The self-hosted engine exposes the same API interface as the Hiya cloud service. This means you can:

1. Develop and test your integration against the cloud API at wss://api.hiya.com/audiointel/...
2. Deploy the self-hosted engine using one of the guides above
3. 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.