AVA Operator setup guide

1. Quick start

This path installs AVA Operator on a supported Asterisk PBX, 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 PBX, 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 detects the PBX, Asterisk and operating system, reports relevant module availability, and checks port conflicts. An unsupported result stops before installation or activation.

Install

Replace the placeholder with your one-time token:

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

The installer shows every proposed PBX integration change and asks for approval before writing it. It activates this Installation, pulls digest-pinned images, starts the services and checks that they stay healthy. A failure after the first write triggers rollback and prints anything that could not be restored.

Do not put a real token in a support ticket, chat message, shell script or documentation.

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.

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 PBXs

Issabel, VitalPBX, Wazo, FreeSWITCH and other platforms may be detected, but are not supported by this release. Detection is not a support promise. The host must be Linux on x86_64/amd64 or aarch64/arm64.

AVA uses the Asterisk already serving the supported PBX. It does not install a second Asterisk beside it.

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.

Internal AVA services bind to loopback. Do not expose their individual ports through a firewall or reverse proxy.

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 compatibility probe runs before activation or host mutation. It inspects the PBX, Asterisk, operating system, modules, ARI state and listening ports. A refusal at this stage means nothing was installed or changed and the token was not spent.

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 system permission for reloads;
• include lines in PBX-supported custom configuration files, pointing to AVA-owned configuration; and
• the AVA-managed routing configuration those includes load.

It does not replace an existing route, trunk, endpoint, extension or manager user. A required change the installer cannot safely place is printed as a manual step rather than silently skipped. Asterisk is reloaded to apply verified changes; it is not restarted.

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

Every mutation is recorded before the next one proceeds. If installation fails, the installer attempts to reverse the journal and reload Asterisk from the restored files. It distinguishes a complete rollback, specific residual paths needing manual review, and intentionally retained prerequisites such as Docker and the Installation identity.

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

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

Start with the Console Overview and Settings pages. On the 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. Also preserve owner, mode and timestamps 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/install-journal.json — uninstall 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

The command reverses the successful install journal, restores original PBX files, removes AVA-specific accounts and include lines, and reloads Asterisk. It does not restart Asterisk.

If any reversal fails, the command keeps the journal, names the residual target and exits unsuccessfully. Resolve that target and rerun; do not delete the journal or backups.

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.

Activation fails

curl -fsSI https://get.agent6789.com/healthz

Check outbound DNS and HTTPS, then rerun the same install command after fixing the named problem. The retained Installation identity prevents a safe retry from creating a second identity.

Image download fails

curl -fsSI https://ghcr.io/v2/
docker info | grep -i proxy

Do not weaken digest verification or run a downloaded binary whose checksum failed.

A service is restarting

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

sudo docker compose -f /opt/ava-operator/docker-compose.yml ps
cat /etc/ava-operator/installation_id
sudo cut -d= -f1 /opt/ava-operator/.env | sort
sudo grep -o '"target":[^,]*' /var/lib/ava-operator/install-journal.json

The third command prints setting names only. Never send the .env file or raw provider credentials. Review logs for tokens, passwords, caller information, transcripts and recordings before sharing them.

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.
• ARI and AMI listen on loopback and use dedicated AVA credentials.
• Internal service ports remain on loopback.
• 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. Access to Customer product data is read-only in this release.

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.