Patients increasingly receive medical advice from both public AI and clinicians. That advice improves when it can reference the complete record across providers, but patients are understandably reluctant to upload hundreds of pages of sensitive records to public AI, and clinicians rarely have the time to review everything. In practice, many decisions end up based on a brief chat rather than the full record.
MAIA introduces a patient-controlled Private AI agent that sits between a patient's complete health record and public AIs. Patients can see and edit chats, share them with clinicians, and manage current medications, a patient summary, a diary of symptoms and observations, relevant references, and a privacy filter that pseudonymizes names before sending anything to public AI.
Unlike Public AI agents, MAIA's trust model does not bundle the AI model policies with the AI hosting policies. The host running the service (DigitalOcean in this implementation) is to be trusted to run this open source code and open source Private AI without modification. The publisher of the open source code and any verifier also needs to be trusted for the integrity of the code they release. Independent verification of code and host is facilitated by the open source design of MAIA.
A key design goal is that the MAIA software author does not need access to anyone's private data. A verifier, even an excellent coding AI, can help confirm the code has no back doors, but they cannot attest to the operational access of whoever provisions a patient's account. This is why MAIA supports user-driven provisioning without third-party access.
When running MAIA, use your own credit card to pay for hosting. If someone else pays for the service, they control the billing account and can likely control access to your data even if the MAIA code has been verified free of back doors.
- Get Started simple, passwordless entry for new users with self-provisioning wizard.
- Passkey registration optional to create web-accessible account.
- Local-only mode (no passkey or password required) for private devices.
- Sign Out with optional local snapshot for deleted account restoration.
- Setup Wizard with multi‑page guidance and feature review.
- My Stuff dialog for private AI agent instruction, document and privacy management.
- Saved Files list with KB inclusion checkboxes and indexing status.
- Upload file from paperclip / file picker.
- PDF Viewer modal with paging.
- Text/Markdown Viewer with page links for source confirmation.
- My Lists linked to PDF source pages.
- Create Categorized Lists from Apple Health file.
- AI-assisted Current Medications patient-reconciled and verified.
- Generate Patient Summary with editing and verification.
- Switch AI provider dropdown (Private AI + public models).
- Saved Chats to local computer and as deep links.
- Open deep link as guest (isolated view).
- Privacy Filtering substitutes all names in a chat for pseudonymity.
- Admin Account and user management page.
- Local folder registration creates the user document and session.
- Agent provisioning (admin-triggered or auto in some flows):
- Creates agent, waits for deployment, stores endpoint + API key.
- File(s) upload:
- Records are prepared for access by the knowledge base (KB)
- KB indexing:
- Uploaded files are indexed into the knowledge base for Private AI retrieval.
- KB attachment:
- Knowledge base is automatically attached to the agent when ready.
- Current Medications / Patient Summary:
- Generated and verified through My Lists and Patient Summary flows.
PUBLIC_APP_URL
Single source: passkey origin and allowed origins are derived from this; RPID is derived as the apex domain (e.g.https://maia.adriang.xyz→ originhttps://maia.adriang.xyz, RPIDadriang.xyz). Used for deep links and app URL.PASSKEY_RPID(optional)
Override RPID if you need a different domain scope (e.g. full hostname instead of apex).PASSKEY_ORIGINS(optional)
Comma-separated allowlist if you need more than the single derived origin.
CLOUDANT_URL,CLOUDANT_USERNAME,CLOUDANT_PASSWORD
Required for user docs, sessions, and audit logs.
When USE_COUCHDB_DROPLET=true, the server auto-creates a DigitalOcean droplet (ubuntu-s-1vcpu-1gb-tor1-01) with Dockerized CouchDB and sets CLOUDANT_* from it. Credentials are stored in Spaces at couchdb/credentials.json so they survive redeploys. Requires DIGITALOCEAN_TOKEN, DIGITALOCEAN_AWS_ACCESS_KEY_ID, DIGITALOCEAN_AWS_SECRET_ACCESS_KEY (bucket name is from NEW-AGENT.txt).
DIGITALOCEAN_TOKEN
Auth for DO GenAI REST API.DO_REGION,DO_PROJECT_ID
Required to create agents and KBs.DO_EMBEDDING_MODEL_ID(optional)
Overrides default embedding model. OpenSearch database UUID is auto-discovered via the DO API and cached in CouchDB.
- Bucket name is fixed in code (see NEW-AGENT.txt;
getSpacesBucketName()). DIGITALOCEAN_AWS_ACCESS_KEY_ID,DIGITALOCEAN_AWS_SECRET_ACCESS_KEY
S3-compatible access to Spaces (endpoint derived fromDO_REGION).
- The OpenSearch cluster is auto-discovered via the DO API and created if needed at first KB creation. One cluster per account is enforced. No env var required.
PUBLIC_APP_URL— Canonical app URL (also drives passkey config; see Passkeys above).PORT— Server listen port.
- App Platform: Runs the frontend + Node server.
- Droplet with Dockerized CouchDB: Cloudant-compatible data store for users, chats, sessions, and audit log. Auto-provisioned when
PUBLIC_APP_URLuses HTTPS (see Environment.md). - GenAI Agent: DigitalOcean Private AI agent per user.
- Knowledge Base: DigitalOcean KB per user, indexed from the Spaces folder datasource.
- OpenSearch 2 Database: Clinical notes indexing/search store with embeddings.
- Spaces File Store: S3-compatible storage for all user files and lists.
npm install
# Create .env with required variables — see Documentation/Environment.md
npm run dev # Vite (frontend)
npm run start # Node (backend)Health check:
curl http://localhost:3001/health