Aywa RuntimeDocumentation
Website Create account

Quickstart

Install a private runtime and verify it before routing calls.

This guide follows the Standard path: create a workspace, generate an install token, install one runtime on an Ubuntu host, open the runtime dashboard, and verify readiness before routing calls.

Why Aywa Runtime

Why this runtime exists

Aywa Runtime was created from the operational constraints behind Aywa's own phone-agent stack: real-time voice latency, tool reliability, BYO providers, predictable infrastructure cost, and a privacy boundary where call data stays in the infrastructure being operated.

The goal is not to add another hosted voice dashboard. The goal is to give serious teams a private execution layer for production voice agents, with the same practical surfaces they need for assistants, phone numbers, calls, tools, webhooks, logs, and provider routing.

Live demo boundary: the public voice demo is a short proof path on Aywa evaluation infrastructure. Production agents, provider API keys, tools, call media, and customer data belong in the private runtime you install.

Private by default

Provider secrets, audio, transcripts, tools, and artifacts live in the deployed runtime environment.

Built for high-volume operations

The architecture is shaped for daily production call traffic, not only local demos or toy agents.

Provider-owned economics

Teams bring their LLM, STT, TTS, telephony, storage, and analytics providers without Aywa platform markup on call minutes.

Voice-first runtime

Turn-taking, endpointing, barge-in, transfer, and webhook delivery are part of the runtime contract.

Private beta flow

Prerequisites

Start with a Linux host that can run Docker, has a public HTTPS endpoint, and can reach the providers you choose for STT, LLM, TTS, telephony, storage, and analytics.

Host

Ubuntu 24.04 LTS, Docker Engine, Docker Compose plugin, inbound 80/443, and SSH access.

Account

Aywa Runtime workspace, active trial or subscription, and an install token scoped to the workspace.

Providers

At least one model provider, one speech-to-text provider, one text-to-speech provider, and a telephony path.

State

Postgres, Redis or Valkey, and S3-compatible artifact storage for production readiness.

Workspace, Runtime Slot, and runtime organization

Aywa Runtime uses three separate scopes. The dashboard creates the commercial workspace automatically when you sign up, the install token binds one Runtime Slot to that workspace, and the deployed runtime creates organization IDs locally for assistants, phone numbers, credentials, files, calls, and logs.

Workspace

Created by signup, trial, or subscription. It owns billing, users, support, licenses, install tokens, and paired runtimes in app.aywaruntime.com.

Runtime Slot

The license entitlement for one active private runtime deployment. Standard includes one production Runtime Slot.

Runtime organization

A business organization inside the private runtime. It isolates assistants, numbers, credentials, files, calls, and logs for one client, brand, department, or SaaS customer workspace.

Generated IDs

Default product flows do not ask you to type organization IDs. Create a runtime organization from a name; the runtime returns the immutable ID for API usage.

Rule of thumb: app.aywaruntime.com manages the paying workspace and Runtime Slots. The deployed runtime manages runtime organizations and their voice resources. Manual organization IDs are only for migration or import tooling that must preserve existing identifiers.

1. Generate an install token

In the dashboard, create a workspace, choose a plan, then generate an install token. Tokens are short-lived, bound to the workspace, and treated like deployment credentials.

VPS scriptCopy the generated command and run it on one Ubuntu host. This is the Standard self-service path.
Docker ComposeDownload the compose template when your team wants to review or customize the generated stack.
Kubernetes HelmDownload the Helm installer and chart when the runtime will run inside a customer-owned cluster.
Standard path: the generated command targets one runtime. Multi-runtime, HA, and load balancing require an Enterprise architecture review.

2. Run the installer

The installer validates the token shape, requires a digest-pinned runtime image, writes the local configuration, prepares Docker Compose, and pulls the official image from the private registry.

Install command 
curl -fsSL https://api.aywaruntime.com/v1/installer | \
              sudo AYWA_INSTALL_TOKEN="$AYWA_INSTALL_TOKEN" \
  RUNTIME_PUBLIC_URL="https://runtime.example.com" \
  AYWA_RUNTIME_IMAGE="$AYWA_RUNTIME_IMAGE" \
  bash

Validate install token

The token is short-lived, bound to the workspace, and consumed when the runtime activates one Runtime Slot.

Pull signed image

The command uses the digest-pinned official image and private registry access issued by the control plane.

Write license material

The runtime receives verification material and renews signed license leases without sending call media to Aywa.

Report heartbeat

The runtime starts locally, reports instance metadata, and unlocks the Open Runtime Dashboard action.

Operator model: app.aywaruntime.com issues the install token, registry access, and signed license lease. The deployed runtime runs the image, stores runtime data, and validates the lease locally.

Kubernetes teams can use the Helm kit from infra/kubernetes. The chart keeps the same digest-pinned image, install token, license lease, and runtime dashboard contract; cluster networking, ingress, registry pull secrets, and SIP/UDP exposure remain under the customer's infrastructure control.

Kubernetes path 
export AYWA_INSTALL_TOKEN="$AYWA_INSTALL_TOKEN"
export RUNTIME_PUBLIC_URL="https://runtime.example.com"
export AYWA_RUNTIME_IMAGE="$AYWA_RUNTIME_IMAGE"
export AYWA_RUNTIME_IMAGE_PULL_SECRET="aywa-runtime-registry"

./infra/kubernetes/install-helm.sh

3. Check runtime readiness

A healthy process is not the same as a production-ready runtime. Use liveness for process checks and readiness for configured dependencies.

GET/healthProcess liveness. Safe for load balancer health probes.
GET/readyzDependency readiness for auth, public URL, storage, providers, WebRTC, and SIP mode.
GET/metricsPrometheus text metrics for production monitoring.
GET/metrics.jsonDashboard-friendly counters for calls, logs, latency, webhooks, and audio events.
Operator commands 
aywa status
aywa update --channel stable
aywa support-bundle --redact

4. Configure providers

The runtime does not need Aywa's control plane to store provider secrets. Configure provider keys in the deployed runtime environment and validate them through /readyz.

Voice pipeline essentials 
VOICE_PIPELINE_ENABLED=true
VOICE_PIPELINE_STT_ENABLED=true
VOICE_PIPELINE_TTS_ENABLED=true
OPENAI_API_KEY=...
DEEPGRAM_API_KEY=...
ELEVENLABS_API_KEY=...
CARTESIA_API_KEY=...

5. Route a staging call

Before production traffic, create one assistant, bind it to a phone number or web transport, run a staging call, then inspect timeline, logs, costs, and webhook attempts.

Minimal API smoke 
curl "$RUNTIME_URL/assistant" \
  -H "Authorization: Bearer $RUNTIME_API_KEY"

curl "$RUNTIME_URL/call" \
  -H "Authorization: Bearer $RUNTIME_API_KEY"