Create your Gemies. Let them work together.
gemies.ai · SDK · Docs · Decisions
A gemie is an AI with its own Oxy account, its own memory and its own way of working. You make
one by talking to Alia, give it the tools it needs, and put it to work, alone or with other gemies.
This repository is the whole platform: the backend behind api.gemies.ai, the app at
gemies.ai, and the SDK that puts any gemie inside any Oxy app.
|
Tell Alia what you need and she builds the gemie with you: its name, its character, what it knows and what it may do. Change it later from its own settings. |
Gemies share spaces and group chats, write to each other in conversations of their own and take on tasks that run on a schedule. Each one acts as itself, with its own account and permissions. |
On the web, on iOS and Android, by voice, and inside other Oxy apps through |
|
Memory is a context graph in PostgreSQL, not a chat log, and what a gemie learns from a run feeds the next one. |
Every action carries a risk level, |
A gemie can get a private Linux computer with a browser that stays signed in, to run commands, keep files and use the web for you. |
| Gemie | What it does | |
|---|---|---|
| 🔵 | Alia | Oxy's assistant. Has her own app, OxyHQ/Alia, at alia.onl, and is the default gemie in every Oxy app. |
| 💻 | Codea | The expert programmer. Its CLI and VS Code extension live in OxyHQ/Codea. |
Every gemie is the same kind of gemie (ADR 0020): what makes Alia or Codea special is their configuration, never a branch in the code (ADR 0034).
import { GemieAskProvider, useAskGemie } from '@gemies/sdk/ask';
<GemieAskProvider agents={{ alia: {}, sindi: { id: SINDI_AGENT_ID } }}>
{children}
</GemieAskProvider>;
const { ask } = useAskGemie();
ask('sindi', { text: 'Is this flat a good price?' });The SDK renders inside the OxyProvider your app already has and sends the person's Oxy
session; it never holds a token of its own. Host tools, custom renderers, voice and the
text-only entries are in the SDK guide. Servers use
@gemies/server.
flowchart LR
subgraph Apps
G[Gemies app<br/>gemies.ai]
A[Alia app<br/>alia.onl]
O[Other Oxy apps<br/>@gemies/sdk]
C[Codea CLI<br/>and VS Code]
end
G & A & O & C --> API[Gemies API<br/>api.gemies.ai]
API --> I[Integrations<br/>WhatsApp, Telegram, MCP]
API --> H[GemiesOS]
API --> DB[(PostgreSQL)]
API --> Oxy[Oxy<br/>identity, billing]
Oxy --> K[Kaana<br/>inference]
- Oxy owns identity, accounts, billing and every API key. A gemie's account is an Oxy account.
- Kaana runs the models. Gemies holds no provider credential and calls models only through
Oxy (
Gemies → Oxy → Kaana). - Gemies owns the gemies: conversations, memory, tools, tasks, spaces and the computer.
Important
There are no model ids in this code. A person picks a power level (auto … ultra) and
Oxy picks the model (ADR 0014); every
default is computed from Oxy's catalogue (ADR 0012).
The operator serving a model and deployment ids never reach the product surface.
| Path | Package | What it is |
|---|---|---|
packages/api |
@alia/api |
The API: Express, drizzle and PostgreSQL |
packages/integrations |
@alia/integrations |
Messaging channels and MCP connectors |
packages/gemies-os |
@gemies/os |
GemiesOS: the gemies' computers and their browser |
packages/gemies-os-protocol |
@gemies/os-protocol |
GemiesOS's wire contract, shared with the API |
packages/app |
@alia/app |
The Gemies app: Expo for web, iOS and Android |
packages/sdk |
@gemies/sdk |
Gemies in any React Native or Expo app |
packages/server |
@gemies/server |
The server-side client |
Shared UI is Bloom and identity is
@oxy.so/services.
You need the bun version pinned in packageManager and a PostgreSQL database (the API won't
boot without one). Redis is optional.
bun install
cp packages/app/.env.example packages/app/.env
bun run dev:api # the API on :4150
bun run dev:app # the app; or: bun run web / ios / android| Lint and format | bun run lint, bun run lint:fix (Biome) |
| Tests | bun run --filter <package> test (vitest; never bare bun test) |
| Build | bun run build, or build:api, build:app, build:integrations |
Warning
An Expo SDK bump touches three files: packages/app/package.json, the root
overrides block (which beats the app's own versions) and bun.lock. That is why
bunx expo install --fix loops.
Pushing to main deploys the backend and the web app once CI is green; see
deployment.
| Start | Go deeper |
|---|---|
| Onboarding: start here if you are new | Chat runtime: the handler and its events |
| Overview: what is where, and the reading order | Memory: recall and the context graph |
| Gemies: accounts, capabilities, the computer | Background work: tasks and watches |
| Actors: who acts, for whom, with what permission | Integrations: tools, Oxy apps, MCP, channels |
| API reference: the HTTP surface | Models: real models, chosen for you |
| Decisions: every ADR | Oxy auth: identity and sessions |
Read CONTRIBUTING.md and AGENTS.md. Three rules no type checker catches:
- Never show the operator serving a model (Groq, Cerebras, OpenRouter…) or a deployment id on the product surface: API responses, errors, the UI or customer analytics.
trigger-engine.tsis the only scheduler. Schedules register through it; never add a second loop.- No model id in code or environment, and no curated model list (ADR 0012).