AIRI source guide

Project AIRI is an open-source virtual-character project. Its repository contains browser, desktop, and mobile applications, shared character modules, and separate services.

A character experience combines several systems. A display model supplies the visible character. A generation provider supplies model responses. Speech, hearing, and external integrations have their own requirements.

airi.loca.zone serves the real AIRI stage-web application. The showcase guide is preserved at help.airi.loca.zone. This wiki explains the source behind the application.

A showcase is not an active character session

Architecture cards and workflow descriptions do not prove that a model, microphone, account, or game integration is active. Read capability-boundaries before treating a source capability as a hosted feature.

Choose a reading path

One project, several surfaces

SurfaceSource locationMain responsibility
Browser applicationapps/stage-webVue application and browser-facing routes
Desktop ver.apps/stage-tamagotchiElectron application, renderer windows, and native integration boundaries
Mobile ver.apps/stage-pocketVue application with Capacitor Android and iOS targets
Shared stage codepackages/stage-ui, packages/stage-pagesCharacter modules, state, components, and shared settings pages
Hosted backendserver/Resource API, authentication, database, and service infrastructure
Server channelpackages/server-runtime, packages/server-sdkA separate communication path for connected runtimes and integrations
flowchart TD
    Visitor[Choose a goal] --> Learn[Understand the source]
    Visitor --> Run[Run a character session]
    Learn --> Guide[Showcase and wiki]
    Run --> Surface[Browser, desktop, or mobile]
    Surface --> Shared[Shared stage modules]
    Shared --> Provider[Configured generation provider]
    Shared --> Character[Display model and renderer]
    Shared --> Audio[Optional hearing and speech]
    Shared --> Services[Optional external services]

Terms that prevent confusion

A provider connects AIRI to an inference service or local subsystem. An inference model is the model selected through that provider.

A display model is character artwork or a 3D asset. An AIRI card holds character information and module selections. Neither resource supplies language-model inference by itself.

The hosted backend and the server channel are separate systems. Their commands, authentication boundaries, and dependencies are not interchangeable.

Source context

This guide describes upstream revision 3da3cf815490b40521e24b22020954e7959d79b4, reviewed on 2026-09-15. It records no hardware acceptance test.

Deployment note (2026-09-27): airi.loca.zone serves the real stage-web application. The preserved showcase remains at help.airi.loca.zone. Both routes now use Authelia one-factor protection. An anonymous sign-in redirect proves the access gate, not application health or inference.

The D-109 receipt verified 42 file hashes, not 42 functional tests. Its provider check saved a placeholder endpoint with no key and sent no chat. The D-146 service and route re-proof did not establish an OMP-backed response. See operations for current runtime verification and remaining prerequisites.

Current D193 source-only update (2026-09-28): the pinned airi-omp bridge is installed and active; its Unix-socket model listing returned HTTP 200 for exact model zai/glm-5.3-flash with socket mode 0600, without generation. Authenticated Chrome on the first promoted artifact found no OMP provider and showed Provider definition not found. That compiled-registration defect has since been repaired: the provider-inference tsdown build and actual exported registry checks passed, and a fresh Vite artifact was promoted with a frontend-only restart.

The repair controller exited 1 at its frontend-readiness timeout and released its lock at 01:56:05Z. A later independent loopback GET at 01:57:18.749Z returned HTTP 200 with bytes matching the new promoted index; it did not erase the controller failure. The subsequent real UI showed native OMP, with omp and zai/glm-5.3-flash selected. At 2026-09-28T04:52:06.830Z, the one observed composer POST (stream: true, zero tools) returned HTTP 403, Same-origin requests only. The DOM showed a Core System error and no assistant tokens. Observation began immediately before composer submission, not during provider setup; this is not a total browser-lifetime request count. The earlier “Health check failed” badge reflects configuration state, not a network health response: inspected OMP source has no validators or automatic completion health probes/retries. This source finding does not retroactively establish deployed-bundle equivalence or the unmeasured historical request total.

The user prompt and 403 error survived a real reload; this is error-state persistence, not generated-output persistence. Reviewed screenshots at widths 390 and 1280 show pale narrow-screen text and a blank avatar stage, not polished UI acceptance. The owned conversation was deleted through native history UI, with its marker absent from the DOM and all IndexedDB stores. Chrome exited 0; the first continuation released at 04:54:58.502320Z and restored the original preload. That attempt produced no diagnostic sidecar, not startup-success evidence. Source places its rejection before bridge forwarding: nginx rewrote Host to loopback while middleware derived the expected public origin from Host. The exact historical header branch remains an inference because those headers were not captured.

Latest terminal result: the deployment-origin correction is now activated and proven by a focused test exit 0 and eight live non-JSON 415/403 guard checks, with a frontend-only restart and unchanged served index. Passive capture covered pre-navigation through cleanup, 05:13:27.460Z–05:17:40.124Z, not the entire spawned browser lifetime. Within that interval it recorded one catalog GET 200 and exactly one completion POST at 2026-09-28T05:14:56.915Z for zai/glm-5.3-flash, streaming requested and zero tools. It returned HTTP 502 startup_network_not_admitted, with no tokens, retry, fallback, or 429. The approved diagnostic sidecar directly bounded this AIRI child at denied loopback catalog startup, before native inference dispatch: inactive inference, zero requests and dispatches. This does not classify Tavern.

The prompt and new error persisted on real reload, not generated output. The owned conversation was removed through native UI, with its marker absent from the DOM and all IndexedDB stores. Chrome exited 0 after acknowledged protocol closure; the controller released at 05:17:42.728999Z and restored the original preload. Exact sidecar bytes were preserved before removal. Origin handling is repaired; native inference remains blocked by loopback catalog startup denial. Completed read-only analysis found no complete permitted startup path: correcting omitted loopback-provider exclusions does not prevent the existing CLI’s selected-provider catalog refresh after cache expiry. A genuine public SDK/ACP seam exists in source, but an installed compatible SDK runtime and its remaining startup-network/guard contracts are not established. This is not a claim that all SDK paths are impossible. No further request or policy widening was performed. See operations for receipts and dated history. This source-only wiki update remains unpublished, the shared publisher is held, and no wiki build was run.

Continue with architecture, read the preserved guide, or open the application.