Alia
🧠 It remembers, and it learns
Context is a persistent graph, not a chat log. context_nodes, context_edges,
context_sources and retrieval_strategies are real PostgreSQL tables
(packages/api/src/db/schema/context-graph.ts),
read through db/autonomy/contextGraphRepository.ts. Learned rules are learning_rules
(packages/api/src/db/schema/agents-support.ts),
read through db/autonomy/learningRuleRepository.ts.
The autonomy runtime classifies the intent, recalls context for it, and feeds the result
of the run back in: classifyIntent, recallContextForIntent and learnFromRun in
packages/api/src/lib/autonomy/.
🛡 Risk before action
Every action an agent can take carries a risk level, R0 through R3, decided in
packages/api/src/lib/agent/governance.ts.
Reversible writes leave a rollback record, so undoing an autonomous change is a lookup
rather than an investigation.
[!IMPORTANT]
Alia has no models of its own. A person picks a power level (auto … ultra) and
Oxy picks the model (ADR 0014);
an API caller may name a real <publisher>/<model> from Oxy's catalogue (GET /catalogue,
filtered to text models with tools). The default,
featured, utility and speech models are computed from that catalogue and Alia's usage,
never hardcoded. Model and publisher names are shown. The operator serving a deployment
and deployment IDs stay off the product surface — product API responses, errors, the
UI, customer-facing analytics — and user-facing errors go through a sanitiser first. See
ADR 0012 and
models in Alia.
The chat runtime
/alia/chat and /v1/chat/completions are served by the same handler
(handleChatCompletions), so the app, Codea and Cowork cannot drift apart in behaviour.
Both are registered in packages/api/src/index.ts with the
same auth (authenticateTokenOrApiKey plus a per-key rate limit); they differ in CORS —
/v1 answers any origin, /alia/chat only Alia's own.
Three roles, none a subset of another
(ADR 0010):
- Kaana is the inference API — models only. Provider credentials live there.
- Oxy is the platform and Oxy Console — accounts, applications, all API keys for
Alia, Kaana and Mention, billing.
- Alia is the assistant, with its own permanent product API:
api.alia.onl/v1/*
and /alia/chat (chat/completions, models, responses, images, audio)
plus /conversations, /shows, /skills, /agents and /catalogue. Three groups
call it, all authorized by Oxy: Alia's own surfaces (the app, Codea — extension and CLI —
and Cowork, on /alia/chat with the user's Oxy session), other applications in the Oxy
ecosystem, and third parties through @alia.onl/sdk. It accepts an OpenAI-compatible
request shape and streams alia.* product events. It does not sunset.
For raw model access use Kaana through Oxy (api.oxy.so/v1); for the assistant use
Alia's API. In both cases the key comes from Oxy Console — Alia issues none. Today Alia's
API authenticates an Oxy user session or service token; the retired alia_sk_* keys are
refused, and the Oxy Console application-key path is not built yet (ADR 0010 § 2).
Hosted inference follows Alia -> Oxy -> Kaana through the published
OxyInferenceClient. Alia stores no upstream provider credential, constructs no
provider client, signs no Kaana envelope and has no direct-provider fallback.
Kaana owns provider credentials and execution state in its PostgreSQL database.
Oxy resolves identity, policy and the exact ordered deployments; Kaana executes
only that signed order and performs failover only within it.
Alia is present only when the feature is an assistant or agent with conversation
state, memory, tools or its own bot identity. A bounded product-owned
operation such as translate, classify, summarize, rewrite or smart reply uses
app -> Oxy -> Kaana and does not detour through Alia. Sindi and Clarity are the
other case: they are ordinary Alia agents that their apps open through the SDK, so
their path is app -> Alia agent -> Oxy -> Kaana, paid by the person using them
(ADR 0020).
Alia’s Oxy-only inference boundary was deployed and read back on 2026-09-10 with
Alia task definition oxy-alia:311: pre-phase migrations and the authenticated
reviewed-profile readiness task completed, ECS reached a healthy two-of-two
steady state, and post-deploy reconciliation succeeded. Public readback returned
ready with the Oxy path configured, the intentionally empty /v1/models, and
only reviewed profiles from /catalogue (since replaced by real models under
ADR 0012). The exclusive canonical Kaana origin
is https://kaana.ai; Alia never configures that origin directly.
Readiness alone does not prove that a provider can answer a chat. The
2026-09-12 incident record
tracks generation checks, recovery changes, and the remaining service-token
and Kaana credential-runtime rollout gates. The
2026-09-13 follow-up records
the separate long-context refusal and its verified serving backport.
/automations is the normalized scheduling and control API for explicit actors,
resources, actions, data flow and autonomy, run by one elected scheduler. Every task has
an actor — Alia by default, or one of the person's agents (actors). The legacy
/triggers model is gone. There is no backward-compatible model resolution endpoint —
POST /v1/resolve-model and POST /v1/report-usage return 410 Gone.
Storage
PostgreSQL through drizzle is the primary store: 80 tables under
packages/api/src/db/schema/, and the API exits at boot if
it cannot connect. Readiness (GET /health/ready) issues a real statement against it.
It is the only store: conversations and messages, agents and their sessions, teams and
reviews, organizations, containers, skills, learning rules, rollback records, canvas
sessions and event-stream entries all live in PostgreSQL.
packages/api/src/db/__tests__/bootWiring.test.ts pins the boot wiring: the boot guards run
before the socket opens, and the expiry sweeper and background services start unconditionally.
@alia/integrations is on PostgreSQL too, under its own schema and its own migration
ledger: the WhatsApp, Telegram and Signal gateways plus the MCP connector OAuth records.
packages/integrations/src/db/__tests__/protectedReads.test.ts
pins how its protected columns are read. Its OAuth secrets are encrypted by the provider rather than by the
column — plain text holding iv:authTag:ciphertext under the same
TOKEN_ENCRYPTION_KEY the API uses — because that is the format they were already
stored in and both processes have to keep agreeing on it.
Packages
Twelve workspaces across eleven directories — packages/alia-codea/webview-ui is its own
workspace entry. Everything lives under packages/.
Runtime
Surfaces
Web
Shared
Identity comes from the Oxy platform rather than from a login system here:
@oxy.so/services and @oxy.so/core, with @oxy.so/bloom
for shared UI. See docs/oxyhq-auth.md.
Quick start
The bun version is pinned in packageManager and CI installs that exact version. You also
need a PostgreSQL instance — the API exits at boot without one. Nothing else is required:
Redis is optional.
bun install
bun run dev # every workspace at once
More usefully, run only what you are working on:
bun run dev:api bun run dev:app
bun run dev:canvas bun run dev:integrations
bun run dev:codea bun run dev:cowork
The app has platform shortcuts at the root:
bun run web # or ios, or android
build and start follow the same pattern as dev.
| Group | Scripts |
|---|
| Build all | bun run build |
| Build one | build:app, build:api, build:canvas, build:integrations |
| Start one | start:app, start:api, start:canvas, start:integrations |
| Lint / format (Biome) | bun run lint (check), bun run lint:fix, bun run format |
[!WARNING]
Bumping an Expo SDK version touches three files, not one. The root package.json
carries an overrides block that pins Expo packages tree wide, and those pins beat
whatever packages/app/package.json declares. That is why bunx expo install --fix
loops forever: the override resets the version it just wrote. A correct bump edits
packages/app/package.json, the root overrides block, and bun.lock.
Documentation
Contributing
Read CONTRIBUTING.md first. Three rules are worth repeating, because
each is easy to break by accident and none is caught by types:
- Never expose the operator serving a model (Groq, Cerebras, OpenRouter…) or a deployment ID
on the product surface — product API responses, errors, the UI, customer-facing
analytics. Model and publisher names are fine; it is a product and privacy boundary, not
a global ban on the words.
trigger-engine.ts is the only scheduler. Structured automation schedules register
through it; do not add a second scheduling loop.- No model id in code or environment, and no curated model list. Alia names real
<publisher>/<model> ids from Oxy's catalogue and computes every default
(ADR 0012); product modes and route:* profiles
are retired. Nothing may be published under the reserved alia/* namespace without the
four conditions ADR 0002 lists.
