AVA Operator setup guide

1. Quick start

This path installs AVA Operator on an exact supported host, proves it with an internal test call, and then creates the first Customer and Agent.

Before you begin

You need root or sudo access to the host, outbound HTTPS access to get.agent6789.com and ghcr.io, an installation token, and credentials for at least one AI provider supported by the installed release.

Run the read-only compatibility check

curl -fsSL https://get.agent6789.com/check | sudo bash

The check inspects the PBX, Asterisk, operating system, modules and ports without installing Operator or activating a token. Detection alone is not approval: the signed installer also checks the exact operating system, architecture and runtime ownership. A passing preliminary check does not make Ubuntu or another unsupported platform eligible.

Install

Request your own token using Get an install token. On the supported host, replace the placeholder with the token from your email:

curl -fsSL https://get.agent6789.com/operator | sudo bash -s -- \
  --token YOUR-INSTALL-TOKEN

Review the proposed integration changes and approval prompts. The signed installation path can install managed Asterisk on a clean host and Docker when required, activate this Installation, pull digest-pinned images and start the services. Follow its final health result and any manual completion steps; downloading images alone is not success.

Treat the token as a secret. The command can be retained in shell history; use a private administrative session and do not share its history, the full token-bearing command, screenshots or logs containing it.

Save the completion details

The final screen prints this Installation's ID, the HTTPS address for the Console, the one-time operator password, and any manual step still required. Copy the password when it appears; it is shown once.

sudo ava-probe reset-operator-password

Use that command if the password is lost. If no public hostname was supplied, the Installation uses a certificate it issued itself. The connection is encrypted, but a browser will warn that the certificate is not publicly trusted.

Add a provider and run Self-test

Sign in to the Console and open Providers. Add a credential for a provider reported as supported by the installed release. Credentials are entered once and are not readable back from the Console. Complete any apply or restart step the provider reports.

Then open Self-test. AVA creates an internal test line and tells you which number to dial from an existing phone on this PBX. Hear the Agent answer before adding a Customer.

A clean host does not already have a phone or Customer trunk. Arrange an appropriate test endpoint or supported PBX connection before attempting a call; installing managed Asterisk does not provision your phones automatically.

The self-test does not reconfigure a phone or route a Customer's number. If no provider credential is usable, it stops before creating the test line and sends you to Providers.

2. Requirements and compatibility

Supported hosts and PBXs

“Vanilla Asterisk” describes the PBX, not support for every Linux distribution. All three rows require Debian 12 amd64. Ubuntu (with or without Asterisk), other Debian releases and ARM/arm64 are not supported.

The authenticated installer on a clean Debian 12 amd64 host installs signed managed-native Asterisk 22. For an existing PBX, matching version numbers alone are not sufficient: package ownership, executable, service and configuration evidence must also pass. Custom/source-built or mixed installations may be refused.

A supported existing FreePBX 17 with Asterisk versions 20 or 22 on Debian 12 amd64 is reused; AVA never installs a second Asterisk beside it. A supported existing vanilla Asterisk 22 on Debian 12 amd64 is reused; AVA never installs a second Asterisk beside it.

Issabel, VitalPBX, Wazo, FreeSWITCH and other platforms may be detected, but are not supported by this release. Detection is not a support promise.

Host and network access

• Root access and a working sudo, shell, curl and SHA-256 utility.
• Enough disk for private container images, application data and any recordings.
• A working Docker Engine, or permission for the installer to install Docker.
• An interactive terminal unless every required answer is supplied with non-interactive flags.
• Outbound HTTPS to get.agent6789.com and ghcr.io.
• Outbound access to each AI provider you configure.

The Console and Customer portal are served over HTTPS on ports selected after the installer checks live listeners. The normal first choices are TCP 443 for the Console and TCP 8443 for the portal, but the installer chooses another documented candidate rather than taking a port already used by the PBX. Use the URLs printed on the completion screen as the authority.

Do not expose internal AVA service ports through a firewall or reverse proxy. Use the installer-provided Console and portal addresses, and configure only the documented SIP/media connectivity for your PBX connection.

Provider requirements

AVA Operator does not include AI-provider usage. You supply provider credentials and pay those providers directly. Availability of providers, models, voices and feature combinations comes from capability contracts in the installed release; the Console is the authority.

3. What the installer changes

AVA Operator is additive, but it is not a zero-write installation.

Read-only phase

The standalone compatibility check is read-only. The signed installer performs additional admission checks before authorizing product/PBX writes. Read the exact failure phase: an admission refusal does not mean the token has never been activated or that no state from an earlier attempt exists.

Changes made with approval

On a supported PBX, the installer may add or update only the AVA-specific integration it shows for approval:

• a dedicated, loopback-only ARI account when one is needed;
• a dedicated, loopback-only AMI account with read system and write system,reporting,originate permissions, as disclosed by the installer; originate permits AVA to initiate calls for supported workflows;
• include lines in PBX-supported custom configuration files, pointing to AVA-owned configuration; and
• the AVA-managed routing configuration those includes load.

For a supported existing PBX, integration uses AVA-specific accounts and includes rather than replacing existing routes, trunks or endpoints. Required manual steps must be completed before routing calls. Integration changes reload the existing Asterisk process. On a clean host, the managed-native path instead installs and starts Asterisk 22; these are different installation paths.

Files and recovery records

The private settings file at /opt/ava-operator/.env contains credentials. Do not copy, email, commit or include it in a support attachment.

Rollback

Recovery depends on the failure phase and authenticated journal. The installer reports what was restored, what needs review and what was intentionally retained, such as Docker or Installation identity. Do not assume a failure returned the entire machine to its original state. Keep the same identity and recovery records for a supported retry.

4. Your first Customer and Agent

Run the internal Self-test first. A working internal call separates Installation and provider problems from Customer routing problems.

Create the Customer

From Customers, select Add customer. Enter the business name and, if useful, its contact email.

Recording is off by default. If you enable Record AVA calls, confirm the Customer's notice and consent requirements before placing calls. The Customer's PBX may also record independently.

Create the Agent

Open Agents and create an Agent with a name, Customer, usable provider credential, optional voice, audio profile, caller greeting and instructions. Every Agent belongs to one Customer so calls remain attributable. Saving an Agent does not by itself route a number to it.

Use Test call from the Agent editor when a ready routing key and applied engine revision are available. The Console reports the actual engine revision that will answer rather than assuming a pending change is live.

Connect the Customer's PBX

Open PBX Connections and select Connect a PBX. The remote-PBX flow requires an accepted Asterisk PBX, a static public source IP and a Customer. You may also add the first DID, the Agent it should reach and the literal Asterisk fallback destination in context,extension,priority form.

The fallback destination is required when adding a DID so calls retain an existing path when AVA is unreachable.

The Console generates a short-lived, single-use enrollment instruction. Run it on the Customer PBX. The bootstrap credential is passed through standard input, never in a command-line flag or URL. The PBX asks before writing its SIP trunk and DID routing, journals the changes, applies them, verifies live Asterisk, and then reports the connection to the Installation.

If several Customers share one hosted PBX, connect the PBX once and add each Customer's routing keys from that Customer's page. A Customer can also use more than one PBX.

Confirm the route before cutover

1. Confirm the PBX is measured as connected.
2. Confirm the routing key is applied to the intended Agent and fallback.
3. Place a supervised call and verify two-way audio, greeting and instructions.
4. Test any handoff.
5. Prove the existing fallback path during a planned AVA-unavailable test.

Do not describe a saved route as live until the Console reports it applied and a real call proves it.

Remove a remote PBX connection

sudo ava-probe unenroll-trunk

Run this on the remote PBX where the enrollment instruction was run, not on an unrelated Operator host. The command reads the recorded trunk manifest, shows what it will reverse and asks for confirmation. Reconcile the corresponding PBX and routing records in the Console after the host change succeeds.

5. Operations and recovery

Routine health check

After a completed installation, start with the Console Overview and Settings pages. On the Operator host (not a remote Customer PBX):

sudo docker compose -f /opt/ava-operator/docker-compose.yml ps

For one service's recent output:

sudo docker compose -f /opt/ava-operator/docker-compose.yml logs --tail 200 control-plane

Raw logs can contain credentials or call information. Review and redact them before sharing. Never send /opt/ava-operator/.env.

Backups

Your normal PBX backup remains required. Use an application-consistent backup or coordinated host/volume snapshot; copying live database files is not a verified restore procedure. Include the actual persistent mounts used by your installed Compose file, recording storage and managed Asterisk state, not just this checklist. Preserve ownership and permissions for:

• /etc/ava-operator/ — the identity the licence is bound to;
• /opt/ava-operator/data/ — databases, call history and recording state;
• /opt/ava-operator/.env — encrypted backup only; it contains live credentials;
• /var/lib/ava-operator/ — the journal, signed runtime receipts and recovery authority; and
• /var/backups/ava-operator/ — original host files replaced during install.

Do not restore an identity from one Installation over another. A restore has not succeeded until identity, settings, data and PBX integration are reconciled and a supervised call passes.

Updates

Do not update by changing image tags or the Core pin by hand. Operator images are digest-pinned and capability contracts are tied to the supported Core release. Use only the release procedure supplied with the update, back up first and retain the previous digests for rollback.

Uninstall

sudo ava-probe appliance-uninstall

Back up first. The command authenticates the recorded installation state before reversing its authorized changes, including product services and PBX integration. For existing-PBX integration, restored configuration is reloaded rather than restarting Asterisk. Do not use uninstall as a general-purpose repair command for an unsupported host or a failed attempt with no committed runtime receipt.

If it refuses or reports residual state, preserve the journal, receipts and backups and follow the exact diagnostic or contact support. Do not manually delete recovery state, edit the journal or remove packages to force a retry.

After success, confirm the original call path with a supervised call. Docker may remain installed because removing a shared host prerequisite automatically is unsafe.

6. Troubleshooting

The compatibility check refuses the PBX

The check names what it found and the supported matrix. Do not bypass the verdict. Fix the named cause or use a supported PBX.

Ubuntu or unsupported_platform

This is an operating-system or architecture refusal, not a missing Asterisk module. Even plain Asterisk on Ubuntu is unsupported. Use a separate Debian 12 amd64 test VM or host and one of the supported paths above. Do not change /etc/os-release, bypass admission, or reinstall the operating system on an existing PBX just to satisfy the installer. A refusal before product writes is not a reason to run uninstall.

Activation fails

curl -fsS https://get.agent6789.com/readyz

This GET checks Hub readiness, not whether your token is valid. Check outbound DNS and HTTPS and keep the exact activation error. Retry only after resolving the reported cause, using the retained Installation identity; do not request new tokens or delete identity files to bypass an error.

Image download fails

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' https://ghcr.io/v2/

HTTP 401 is expected for this unauthenticated registry check. It shows the registry answered; it does not test the installer's private-image authorization. Preserve the installer's exact error and contact support if authentication fails. Do not weaken digest verification, manually install prerequisites to bypass recovery, or share Docker authentication files.

A service is restarting

Use these commands only if the installed Compose file still exists. After rollback removes it, use the installer's reported failure log instead; do not recreate the directory or invoke Compose manually to bypass the installer.

sudo docker compose -f /opt/ava-operator/docker-compose.yml ps
sudo docker compose -f /opt/ava-operator/docker-compose.yml logs --tail 200 SERVICE

Replace SERVICE with the service named by the installer. Fix the exact rejected setting or filesystem permission in its output. Do not paste .env values into support.

The Console does not open

Use the exact HTTPS URL printed by the installer. The port may not be 443 when the PBX web interface already uses it. A browser trust warning is expected when the Installation issued its own certificate.

sudo docker compose -f /opt/ava-operator/docker-compose.yml logs --tail 200 caddy
sudo docker compose -f /opt/ava-operator/docker-compose.yml logs --tail 200 control-plane

A remote PBX will not connect

Generate a fresh enrollment instruction from PBX Connections. Confirm the PBX passed its check, its source IP is static and matches the Console entry, it can reach the Installation's HTTPS address, and the enrollment command runs as root.

If the host reports that the trunk was written but the callback failed, inspect PBX Connections before retrying. Do not create a duplicate PBX record to hide an incomplete callback.

A failed write reports residual state

Safe support information

cat /etc/os-release
uname -m

Include the exact error, whether this was a fresh install or retry, and your PBX/Asterisk version if already installed. For an Installation that has an identity file, you can retrieve its ID with sudo cat /etc/ava-operator/installation_id. Missing product files after a pre-write refusal are expected; do not create them.

Never send the token-bearing install command, .env, Docker authentication files or provider credentials. Review any failure log for tokens, passwords, caller information, transcripts and recordings before sharing it.

Still blocked? Email [email protected] with the exact error and the redacted information above.

7. Security and data

Where call data stays

AVA Operator runs on the operator-managed PBX. Its databases, call history, transcripts and recording state live in the Installation's local data volume. The product does not send product telemetry to Agent6789 in this release.

During a call, the Installation sends the audio, text and instructions required by the AI providers the operator configured. Those providers process data under their own terms. Choose providers and regions appropriate for each Customer.

The public Agent6789 website's consent-based analytics is separate from the installed product. The Console bundles its fonts and does not load Google Analytics.

Recordings

Recording is off by default per Customer. When enabled, recordings remain on operator-managed storage mounted into the Installation. Support-bundle manifests exclude the recording tree by default. Export is a separate, audited operator action.

The operator is responsible for recording notices, consent, retention and access rules. A Customer's PBX may record the same call under a separate policy.

Credentials and access

• Provider credentials are entered once and are not readable back from the Console.
• Values stored through the Secrets library are encrypted and scoped.
• AVA's dedicated ARI and AMI accounts restrict access to loopback. Existing PBX listeners may retain their configured bindings; review those separately rather than assuming AVA makes them private.
• Internal services are not public access points; preserve the installed network boundaries.
• The Installation settings file contains live credentials and must be treated as a secret.

The Customer portal uses emailed one-time codes. It is not ready for Customers until a mail provider is configured and a test code has arrived. Customers can view their own permitted data and use the Requests and Connections features available to them; this is not unrestricted access to the operator Console.

Public signup, token delivery, activation and licensing records are separate from appliance call data. See the Privacy Policy for that boundary.

Availability boundary

The Hub is used for installation, licensing and billing-related management. A Hub outage does not sit in the call path. Licence state may refuse new management actions, but it does not terminate existing Agents or calls.

Before sharing support material

1. Reproduce the problem without exposing a caller's live call.
2. Review every included file.
3. Redact credentials, caller identifiers and unnecessary call content.
4. Confirm recordings are absent unless the Customer explicitly authorised that specific audio for support.