Configuration Reference

Every environment variable AVA reads, grouped by area, with its type, default, whether it is required, and what it changes. The authoritative template is .env.example in the repo root — this document explains it.

How config is loaded. In development the custom server loads .env.local from the repo root (with override: true, so .env.local wins over shell vars). In the container, your env file is mounted read-only at /app/.env.local and docker-entrypoint.sh validates the required set before the server starts. Almost every non-NEXT_PUBLIC_* value is read at call time, so you can change it and restart the container with no rebuild.

Two special cases:

• NEXT_PUBLIC_* variables are compiled into the browser bundle at build time (Dockerfile build args). Changing them requires a rebuild, not just a restart.
• AUTOTASK_API_SECRET is read raw from the env file (bypassing dotenv variable-expansion) because it commonly contains $. Wrap it in double quotes.

Legend: Required = the container refuses to start without it (or it is required for the configured AI provider). Recommended = boots without it but you should set it for a correct deployment. Optional = safe default.

Required to boot

These are validated by docker-entrypoint.sh; a missing one aborts startup with a clear error naming the variable.

NEXTAUTH_SECRET strength checks

Beyond mere presence, the entrypoint enforces secret quality at boot:

• Shorter than 32 characters → startup aborts. This secret signs every engineer and client session, so it must be long and random.
• Placeholder-looking values are refused (for example anything containing changeme) — a value copy-pasted from documentation cannot reach production.

Generate a real one:

openssl rand -base64 48

The entrypoint also warns (without failing) if the mounted env file is group- or world-readable — it holds live secrets, so keep it chmod 600.

AutoTask — default ticket values

Picklist IDs are specific to your AutoTask instance; discover them with npx tsx scripts/discover-picklists.ts. Do not copy another instance's numbers.

⚠️ Warning — the four priority vars are not a graduated default. There is no built-in per-priority-level mapping. Each of AUTOTASK_PRIORITY_P1..P4 resolves independently: if a given Pn is unset, it falls through to the single shared AUTOTASK_DEFAULT_TICKET_PRIORITY, and if that is also unset, to a hardcoded 3. If you do not set these four vars, ALL AI-triaged chats file at the same AT priority, regardless of what the AI determined — P1/critical and P4/low tickets become indistinguishable in AutoTask. Discover your instance's priority picklist IDs with npx tsx scripts/discover-picklists.ts and set all four.

Priority editing in the engineer console (v1.8.0). Engineers can change a ticket's priority from the chat's ticket panel or with /priority. That is only enabled when all four of AUTOTASK_PRIORITY_P1..P4 are set and pairwise distinct, and every one of the four IDs is an active value of your live AT priority picklist — otherwise AVA cannot tell which AT priority a P-level means (or AT would refuse the write), so the Priority field is read-only (hint: "Priority editing isn't configured — ask your administrator") and AVA refuses priority changes instead of writing a guessed value. A typical mapping, using your own picklist IDs:

AUTOTASK_PRIORITY_P1=4   # your "Critical" priority id
AUTOTASK_PRIORITY_P2=1   # your "High" priority id
AUTOTASK_PRIORITY_P3=2   # your "Medium" priority id
AUTOTASK_PRIORITY_P4=3   # your "Low" priority id

A priority change also updates the chat's P-level in the queue and header. Status editing needs no config: the status list is read live from your AT picklist, and "Complete" is never offered there (tickets are completed through the wrap-up flow). Complete is recognised by its label and by its picklist ID — AT's system value 5 — so a renamed or localized Complete status is still refused; if your instance's Complete status uses a different ID, set AUTOTASK_COMPLETE_STATUS_ID (below).

Engineer internal notes & ticket edits (v1.8.0)

Internal notes are never shown to the client — not in the chat, not in emails, not in the client-facing AT note, the resolution field or the time entry. AutoTask workflow rules still apply to every write AVA makes, so read the workflow-rule caution in autotask-setup.md (Step 7, "Workflow rules and the engineer console") before go-live. How these features look to engineers is covered in engineer-console.md.

Resource role ID — AUTOTASK_DEFAULT_ROLE_ID

Resolution is warn-not-fail: if unset — or set to something that isn't a positive integer — AVA logs a one-time warning and falls back to a built-in role ID that will not match your AutoTask instance. Role IDs are per-instance, so always set your own (find them with GET /Roles or via your AT admin's Roles list). An invalid value never blocks startup; it just degrades to the fallback — which would post time entries under a role your instance doesn't recognize.

Catchall company — AUTOTASK_CATCHALL_COMPANY_ID

If unset, unknown-domain chats start without an AutoTask ticket and fall into a degraded recovery path (late ticket creation at close, or an engineer-confirmed close-without-sync). Set it to avoid that path entirely. Note 0 is a valid AutoTask company ID — AVA treats "unset" and "0" differently, so an explicit 0 does enable the catchall. Find a company's ID with npx tsx scripts/test-autotask.ts <domain>.

Microsoft Entra ID

AI / LLM

AVA's AI layer (triage, similar-resolution suggestions, trend summaries, field summarization, the engineer /draft / /rewrite / /summarize commands, and the close-flow ticket summary) is provider-agnostic: it runs on the Vercel AI SDK behind two role-based model slots, LLM_FAST and LLM_QUALITY, supporting Anthropic (default), OpenAI, Google Gemini, and OpenRouter.

The full reference — provider matrix, provider/model string format, conditional key requirements, which features use which tier, and the timeout caveat — lives in ai-providers.md. Quick summary:

Engineer AI cost guard (v1.8.0)

The engineer-console AI commands (/draft, /rewrite, /summarize, the wrap-up Summarize and "Draft all" buttons, similar resolutions and trends) share an in-memory budget. Client-side AI triage is not counted (it is rate-limited per IP instead).

Only one call per command per chat runs at a time (a double-click is refused). Counters reset when the container restarts. Each call writes one [ai-usage] log line with ids, model, token counts, latency and outcome — never the prompt or the output — so you can track spend from your logs. With the defaults and a Haiku-class fast model (~6k input + 350 output tokens per call), the worst case is roughly $0.25 per chat and $0.50 per engineer-hour. Invalid values log a warning and use the default.

Application & networking

Trusted proxy — NGINX_TRUSTED_PROXY

Trust is opt-in only. Set it to exactly 1 when — and only when — the app always sits behind your own reverse proxy (as in the provided compose + nginx templates, where nginx sets the header from the actual connection address). Any other value — including unset, and even with NODE_ENV=production — means the header is ignored. When multiple comma-separated hops are present, AVA uses the entry appended by the proxy nearest to it.

If you forget it behind a proxy: AVA can't tell visitors apart, so every visitor shares one set of per-IP limits (chat starts, uploads) and clients start hitting "too many sessions" together. Behind the template nginx, always set NGINX_TRUSTED_PROXY=1.

Bot protection & email

Recipient addresses

reCAPTCHA verification behavior

reCAPTCHA verification is fail-closed by default everywhere: a missing secret, a missing token, a network error reaching Google, or a low score all reject the request.

RECAPTCHA_DEV_BYPASS is the one narrow escape hatch, for development and test environments only. It fails open (allows the request) when — and only when — both hold:

• NODE_ENV is not production, and
• RECAPTCHA_DEV_BYPASS is set to exactly true (not 1, not yes).

In production it is refused outright — when NODE_ENV=production, no value of this variable can re-enable the bypass; verification always fails closed. Leave it unset everywhere except a local dev box that has no real reCAPTCHA key. The siteverify call also enforces an outbound timeout (RECAPTCHA_TIMEOUT_MS, below) so a hung Google endpoint cannot stall the request.

File uploads

Chat participants (client and engineer) can attach files to a session. The constraints, all enforced server-side:

• Per-file size cap: 5 MB (fixed). Larger files are rejected with HTTP 413.
• Type allowlist: PNG, JPEG, GIF, HEIC, PDF, XLSX, DOCX, EML, ZIP, TXT, CSV.
• Content check: a file's content must match the type it claims. Files are stored under generated names; images display inline, and every other type downloads as an attachment.
• Access: clients can only open their own chat's attachments; an active chat's attachments are visible to the engineer handling it, and a closed chat's attachments to any signed-in engineer (Archives).

Upload budget, quota & retention

All optional; defaults shown. Invalid values warn once and fall back to the default.

Business hours

All optional; the defaults reproduce Mon–Fri 6 AM–6 PM Pacific. Invalid values validate-and-fall-back (they never throw). The configured schedule also drives the client-facing availability copy — the off-hours message quotes your actual hours, not a hardcoded string.

White-label / branding

AVA ships vendor-neutral: with none of these set, the app presents as a generic "Your Company" deployment with no phone number and no client-portal link. Every deploying MSP sets its identity here. All values are read at call time — set them in your runtime env file and restart; no rebuild. See white-label.md for the full walkthrough, worked example, and verification checklist.

Recipient/sender addresses (SUPPORT_FALLBACK_EMAIL, FEEDBACK_EMAIL, REPORTS_EMAIL, SMTP2GO_FROM) are part of the same identity surface but are documented under Bot protection & email since they carry required/fail-closed semantics.

Session limits

External-call timeouts

All optional; defaults shown. Milliseconds.

NinjaOne (optional, read-only device glance)

Off by default. With NINJAONE_BASE_URL / NINJAONE_CLIENT_ID / NINJAONE_CLIENT_SECRET unset, the feature is completely dormant — the engineer dashboard's client-context panel behaves byte-for-byte as if it didn't exist (no Device section renders, no NinjaOne network calls are ever made). Set all three to turn it on.

What it does. When a client starts a chat, AVA tries to identify their machine and shows the engineer a read-only "device at a glance" card in the chat's context panel — online/offline status, last boot, disk free, pending/failed OS patches, antivirus state, public/private IP, make/model/RAM, last logged-on user, and recent alerts — plus a one-click "Open in NinjaOne" deep link to the device's dashboard page. It never modifies anything: the NinjaOne API credential is scoped to monitoring only, and the NinjaOne client exposes GET requests exclusively. Two resolution paths work independently of each other:

• AutoTask-only baseline (no NinjaOne credentials needed). If your AutoTask instance already syncs NinjaOne data onto Configuration Items (the NinjaRMM-RemoteUrl / -BackgroundUrl / -Antivirus / -PrivateIpAddress / -DeviceUID UDFs), AVA matches the chat's AutoTask company + reported hostname to a Configuration Item and shows those UDF facts plus the deep link parsed out of the remote-URL UDF — even with NINJAONE_* fully unset.
• Live NinjaOne API layer (optional, adds live telemetry). When the three vars above are set, AVA additionally queries the NinjaOne API directly for live device data and can fall back to a hostname/user search when no Configuration Item matched.

Create the API client (NinjaOne admin)

1. In NinjaOne: Administration → Apps → API → Client App IDs → Add.
2. Platform: API Services (machine-to-machine).
3. Scope: Monitoring only — do not grant management or any write scope. This is a least-privilege design choice, not just a convention: the resulting credential cannot modify a device, run a script, or trigger an action at all.
4. Grant type: Client Credentials. No redirect URI is needed (this is a server-to-server, not an interactive OAuth flow).
5. Copy the generated Client ID and Client Secret into your env (below).

Env vars

All three required vars must be set together — the feature is all-or-nothing. NINJAONE_ENRICH_TICKETS is independent of those three and defaults to off even when they're set.

UDF merge pre-flight (before enabling NINJAONE_ENRICH_TICKETS)

AT's PATCH /Tickets handling of the userDefinedFields array is instance-dependent: some configurations merge the array, others could blank UDFs the PATCH omits. Before flipping the flag on, verify your instance merges:

1. Create a throwaway scrap ticket in AutoTask.
2. Seed two different UDFs on it with known values.
3. PATCH the ticket updating only one of the two UDFs.
4. Confirm the other UDF survives untouched.

Only enable NINJAONE_ENRICH_TICKETS=true after step 4 passes. Another instance's pre-flight result does not transfer to yours.

Region base URLs

Use the same NinjaOne data-center region your admin console login URL shows:

Systray URL setup — auto-identifying the client's machine

AVA resolves "which machine is this?" most reliably when the client reaches the chat page via a link that carries systray-substituted hints. NinjaOne's systray custom URL items support ${HOSTNAME} / $USERNAME / ${DOMAIN} placeholders, substituted at click time. In your NinjaOne branding/systray policy, set the chat link to:

https://<your-chat-domain>/?host=${HOSTNAME}&user=$USERNAME&domain=${DOMAIN}

AVA captures these once on page load, forwards them with the chat-start request, and stores them on the session as display + lookup hints only — never an authorization signal. Omitting the query string entirely still works; the device card simply has less to search on (falls back to a user/email-based search when NinjaOne is configured, or shows a "no managed device matched" empty state otherwise).

Validate your setup

npx tsx scripts/test-ninjaone.ts [hostname]

Confirms config presence, exercises the real OAuth2 client-credentials token exchange, lists organizations and a few devices, and — with a hostname argument — runs the same hostname search the device-resolution pipeline uses.

Honest limitations

• The "Open in NinjaOne" deep link requires the engineer to already be logged into NinjaOne in their browser — it is a console URL, not a standalone remote-session launcher.
• No remote-session launch, no reboot/script actions — this is a strictly read-only "glance" feature. Any action capability is a separate, not-yet-built tier.
• Systray hints are client-reported, exactly like the browser user agent — useful for lookup, never trusted for identity/authorization.
• Live telemetry values (disk, patches, AV, alerts) reflect NinjaOne's own last-check-in data for that device, not a real-time poll triggered by the chat.

See also

• quickstart.md — the ordered bring-up that sets these.
• ai-providers.md — the full AI provider & model reference.
• white-label.md — branding your deployment.
• requirements.md — accounts and prerequisites.
• engineer-console.md — what the engineer-console variables above look like to your engineers.