iYan Documentation on iYan Docs

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Self-hosted iYan Enterprise is deployed with Ansible. All images are pre-built and pulled from the iYan private registry — no compilation required.

Architecture

Platform Overview

Mon, 01 Jan 0001 00:00:00 +0000

The Alpha Platform is composed of the following services. Each runs as a container in the enterprise deployment; the license server is the only component hosted by the vendor off-site.

Core services

Service	Role	Description
Kira	AI agent backend	Core AI agent backend. Serves the REST API, SSE streaming, authentication, and the agent orchestration loop.
Misa	Worker	Async task worker: images, diagrams, voice transcription, email, cron jobs. Consumes tasks from RabbitMQ.
Ryuk	Web frontend	nginx serving the React 19 + Vite web SPA. Reverse-proxies API calls to Kira.
Web SPA	UI	React 19 + Vite web application (chat, vault, kanban, settings, playground).
Mobile app	UI (planned)	Release planned for 2027.

Infrastructure services

Service	Role	Description
RabbitMQ	Message broker	AMQP broker carrying async tasks between Kira and Misa.
PostgreSQL	Vector store	PostgreSQL with the `pgvector` extension — stores embeddings for RAG.
Ollama	LLM inference	Local LLM and embedding model server. Model-agnostic.
Docling	Document conversion	Converts PDF, DOCX, PPTX into markdown for RAG ingestion.
SearXNG	Web search	Privacy-respecting meta search engine used by the web search tool.
MCPJungle	MCP gateway	MCP (Model Context Protocol) gateway and server management.

External integrations

Integration	Type	Description
Google Drive	MCP provider	File storage.
Gmail	MCP provider	Email.
Outlook	MCP provider	Email and calendar.
Notion	MCP provider	Notes and docs.
Odoo	MCP (in-network)	Example of an MCP server inside the enterprise network.
SSO	Auth	Single sign-on (Google, Microsoft, LinkedIn).

Vendor-hosted

Service	Description
License Server	Enterprise license authority at `license.iyan.ca`. Validates enterprise licenses; never deployed on the client site.

Agent-to-agent

The platform supports agent-to-agent interaction — you can use your favorite agent client (opencode, claudecode, …) against the iYan API.

Kira Backend

Mon, 01 Jan 0001 00:00:00 +0000

Kira is the core AI agent backend. It is a single binary that serves the REST API, authenticates users, orchestrates the agent loop, and manages per-user isolation.

Responsibilities

Kira handles six jobs:

Responsibility	Description
API server	REST + SSE streaming endpoints for chat, vault, tasks, cron, and user settings.
Authentication	JWT-based auth with refresh tokens, admin roles, and per-user isolation.
Agent orchestration	Receives messages, loads session history, retrieves RAG context, calls the LLM, executes tools, and streams the response back.
Tool execution	Runs actions requested by the LLM: file I/O in the vault, web search, email, document conversion, cron scheduling, sub-agent spawning.
Multi-user isolation	Each user gets their own agent instance, vault, vector store, and cron jobs.
Enterprise licensing	Validates the license against the vendor server, enforces seat counts, and gates enterprise features.

LLM providers

The backend talks to any OpenAI-compatible LLM endpoint. Out of the box it supports:

Licensing

Mon, 01 Jan 0001 00:00:00 +0000

The enterprise edition uses a vendor-hosted license server. No license server runs on your infrastructure.

How it works

iYan issues a license file (license.jwt) for your installation

You place the file on your server:

 scp license.jwt debian@YOUR_SERVER_IP:/tmp/license.jwt
ssh debian@YOUR_SERVER_IP "sudo cp /tmp/license.jwt /opt/iyan-data/kira/license.jwt"

Set the edition mode to enterprise in ansible/group_vars/all.yml:
```
 kira_edition_mode: enterprise
 
```

Redeploy or restart Kira:

 ansible-playbook -i ansible/hosts.ini ansible/playbook.yml
# or just: ssh debian@YOUR_SERVER_IP "docker restart iyan-kira"

Kira validates the license against https://license.iyan.ca on startup and every hour. A 72-hour grace period allows temporary server outages.

Getting your installation ID

To request a license from iYan, provide your installation ID:

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

`edition` config section

Field	Default	Description
`mode`	`auto`	`auto` resolves to the build edition. `saas` forces SaaS (dev override). `enterprise` requires a valid license.
`license_file`	`~/.kira/license.jwt`	Path to the signed license token.
`license_server_url`	`https://license.iyan.ca`	Vendor license server base URL.
`heartbeat_interval`	`1h`	How often kira contacts the license server.
`grace_period`	`72h`	Tolerate license-server outage before degrading.
`install_id_file`	`~/.kira/install.id`	Installation identity (auto-generated on first startup).

Example config:

 agent:
 name: kira
 data_dir: /home/kira/.kira
 log_level: info

api:
 port: 8080
 admin_email: admin@yourcompany.com
 admin_password: <change-me>

memory:
 obsidian_vault: /vault
 embeddings:
 store: pgvector
 connection_string: "postgres://..."

edition:
 mode: enterprise # auto | saas | enterprise
 license_file: /home/kira/.kira/license.jwt
 license_server_url: https://license.iyan.ca
 heartbeat_interval: 1h
 grace_period: 72h
 install_id_file: /home/kira/.kira/install.id

misa:
 amqp_url: "amqp://guest:guest@rabbitmq:5672/"

Environment variable overrides

All config fields can be overridden via env vars:

Data Flow

Mon, 01 Jan 0001 00:00:00 +0000

Synchronous request flow

 User (Web / Mobile / Agent client)
 ↓
[Ryuk nginx] → reverse proxy → [Kira API]
 ↓
Auth + routing + session load
 ↓
Memory search (RAG context retrieval)
 ↓
Build system prompt (context + tools + history)
 ↓
LLM call (Ollama / configured provider)
 ↓
[While the LLM requests tools]:
 Execute tool → feed result back to LLM
 ↓
Format response → stream back to user via SSE

Async task flow

Long-running work (images, voice, email, cron) is offloaded to Misa via RabbitMQ so the API stays responsive:

Database

Mon, 01 Jan 0001 00:00:00 +0000

iYan uses two storage layers: an application database for users, sessions, and jobs, and a vector database for RAG embeddings.

Application database

Operational data (users, sessions, settings, cron jobs, usage logs) is stored in an embedded SQLite database managed by the backend.

Main data collections

Collection	Usage
`users`	User accounts (with plans, quotas, preferences)
`user_states`	Last session per user
`user_configs`	Appearance / behavior settings
`user_cron_jobs`	Scheduled jobs per user
`user_usage_logs`	Consumption tracking
`system_settings`	Global configuration (admin)
`running_tasks`	Tasks currently executing

Vector store (embeddings)

Embeddings for RAG are stored in PostgreSQL with pgvector in the enterprise deployment (a centralised instance), or per-user SQLite in single-user mode. This is configured in memory.embeddings.store: pgvector with a connection_string.

Service Management

Mon, 01 Jan 0001 00:00:00 +0000

Start / stop / restart

 # Start all services
cd /opt/iyan-entreprise && docker compose up -d

# Stop all services
cd /opt/iyan-entreprise && docker compose down

# Restart a specific service
docker restart iyan-kira

# Pull updated images and restart
cd /opt/iyan-entreprise && docker compose pull && docker compose up -d --force-recreate

Logs

 docker logs -f iyan-kira
docker logs -f iyan-misa
docker logs -f iyan-ollama

Ollama model management

 # List installed models
docker exec iyan-ollama ollama list

# Pull a new model
docker exec iyan-ollama ollama pull <model-name>

# Remove a model
docker exec iyan-ollama ollama rm <model-name>

Pre-installed models

Purpose	Model	Size
Primary LLM	`qwen3.5:cloud`	~4GB
Embeddings	`nomic-embed-text-v2-moe:latest`	~1GB
Subagent	`llama3.2:latest`	~2GB

Updating

To update to a new version of iYan:

Backup and Restore

Mon, 01 Jan 0001 00:00:00 +0000

Backup

 # Full backup (stop services first for consistency)
cd /opt/iyan-entreprise && docker compose down
tar czf iyan-backup-$(date +%Y%m%d).tar.gz /opt/iyan-data/
docker compose up -d

# PocketBase only
docker exec iyan-kira sqlite3 /home/kira/.kira/pb/data.db ".backup /dev/stdout" > pb-backup.sql

# PostgreSQL (embeddings)
docker exec iyan-postgres pg_dump -U iyan iyan > pg-backup.sql

Restore

 # Stop services
cd /opt/iyan-entreprise && docker compose down

# Restore data
tar xzf iyan-backup-YYYYMMDD.tar.gz -C /

# Start services
docker compose up -d

Scalability

Mon, 01 Jan 0001 00:00:00 +0000

Resource	Strategy
API	Stateless — can scale horizontally
SQLite	Per user — avoids global locks
Embeddings	SQLite per user or pgvector centralised
Filesystem	Per user — partitioned naturally
LLM	Externalised — no local GPU load (Ollama can be split to its own host)
Misa workers	Scale horizontally behind RabbitMQ
Ollama	Can run on a dedicated GPU host

Scaling Misa

Because Misa consumes from RabbitMQ, you can run multiple Misa replicas to parallelise image generation, document conversion, and email processing:

Enterprise API

Mon, 01 Jan 0001 00:00:00 +0000

All endpoints are under /kira/enterprise/* and only mounted when the enterprise provider is active.

Method	Path	Auth	Description
GET	`/kira/enterprise/license`	Any auth	License status snapshot
POST	`/kira/enterprise/license/upload`	Superuser	Upload a new license token
POST	`/kira/enterprise/trial/activate`	Superuser	Start a 7-day trial
GET	`/kira/enterprise/seats`	Superuser	Seat usage report

License status response

 {
 "edition": "enterprise",
 "valid": true,
 "trial": false,
 "max_users": 50,
 "current_users": 12,
 "expires_at": "2027-07-18T15:42:34Z",
 "grace_until": null,
 "reason": ""
}

Health check

The /kira/health endpoint includes the edition and license state:

Security

Mon, 01 Jan 0001 00:00:00 +0000

Change ALL default passwords in ansible/group_vars/all.yml before deploying.
Generate a BYOK master key: openssl rand -hex 32.
The license server is hosted by iYan — no credentials needed on your side.
RabbitMQ management UI is exposed on port 15672 — restrict access in production (firewall / reverse proxy).
PocketBase admin UI is at http://YOUR_SERVER:8080/_/ — restrict access in production.
All services use unless-stopped restart policy.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Kira won’t start

 # Check logs
docker logs iyan-kira

# Common issues:
# - License invalid: place license.jwt at /opt/iyan-data/kira/license.jwt
# - Database unreachable: check postgres is healthy (docker ps)
# - Ollama not ready: check ollama is running and has models (docker exec iyan-ollama ollama list)
# - RabbitMQ auth failed: verify rabbitmq_password matches in .env and config/kira.yaml

Misa won’t start

 docker logs iyan-misa

# Common issue: "authentication failed with status 400"
# Fix: verify kira_admin_password matches in .env and config/misa.yaml
# Or: create the PocketBase superuser first:
# docker exec iyan-kira kira superuser admin@yourcompany.com YourPassword

Ollama out of memory

 # Check available memory
docker stats iyan-ollama

# Use smaller models or increase server RAM
# Edit ansible/group_vars/all.yml and change model names

 # Fix permissions
chown -R 999:999 /opt/iyan-data/rabbitmq/
chmod 600 /opt/iyan-data/rabbitmq/.erlang.cookie
docker restart iyan-rabbitmq

Disk full

 # Check disk usage
df -h

# Clean unused Docker images
docker image prune -f

# Remove unused Ollama models
docker exec iyan-ollama ollama rm <model-name>

License errors

Symptom	Cause	Fix
`enterprise: no valid license` at startup	Missing or invalid license file	Upload a license via admin UI or mount the file
`enterprise: license expired`	License `expires_at` is in the past	Renew via vendor, upload new license
`enterprise: license revoked`	Vendor revoked the license	Contact vendor
`enterprise: install_id mismatch`	License bound to a different install	Re-issue license for this install_id
Health shows `license: unreachable`	License server down for > grace period	Fix connectivity or upload an offline license
User creation returns 409	Over capacity	Reduce users or upgrade license
Enterprise routes 404	SaaS binary or mode=saas	Use the enterprise image with mode=auto/enterprise

iYan Documentation on iYan Docs

Installation

Architecture link

Platform Overview

Core services link

Infrastructure services link

External integrations link

Vendor-hosted link

Agent-to-agent link

Kira Backend

Responsibilities link

LLM providers link

Licensing

How it works link

Getting your installation ID link

Configuration

edition config section link

Environment variable overrides link

Data Flow

Synchronous request flow link

Async task flow link

Database

Application database link

Main data collections link

Vector store (embeddings) link

Service Management

Start / stop / restart link

Logs link

Ollama model management link

Pre-installed models link

Updating link

Backup and Restore

Backup link

Restore link

Scalability

Scaling Misa link

Enterprise API

License status response link

Health check link

Security

Troubleshooting

Kira won’t start link

Misa won’t start link

Ollama out of memory link

RabbitMQ cookie error link

Disk full link

License errors link

Architecture

Core services

Infrastructure services

External integrations

Vendor-hosted

Agent-to-agent

Responsibilities

LLM providers

How it works

Getting your installation ID

`edition` config section

Environment variable overrides

Synchronous request flow

Async task flow

Application database

Main data collections

Vector store (embeddings)

Start / stop / restart

Logs

Ollama model management

Pre-installed models

Updating

Backup

Restore

Scaling Misa

License status response

Health check

Kira won’t start

Misa won’t start

Ollama out of memory

RabbitMQ cookie error

Disk full

License errors