Metadata-Version: 2.5
Name: oi-agent
Version: 1.0.2
Summary: Smarter self-hosted AI assistant for multiple users and agents, built on oi-harness
Project-URL: Homepage, https://github.com/akankofik-dev/Oi
Project-URL: Repository, https://github.com/akankofik-dev/Oi
Project-URL: Issues, https://github.com/akankofik-dev/Oi/issues
Project-URL: Changelog, https://github.com/akankofik-dev/Oi/blob/main/CHANGELOG.md
Author: akankofik-dev
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: acme>=5.6.0
Requires-Dist: apscheduler<4,>=3.10
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: boto3>=1.40.61
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=41
Requires-Dist: edge-tts>=6.1
Requires-Dist: fastapi>=0.110
Requires-Dist: josepy>=2.2.0
Requires-Dist: langchain-core>=1.4.8
Requires-Dist: langgraph-checkpoint-postgres>=2.0
Requires-Dist: lark-oapi>=1.7.3
Requires-Dist: ldap3>=2.9.1
Requires-Dist: mcp<2,>=1.9
Requires-Dist: oi-browser>=1.0.0
Requires-Dist: oi-gateway>=1.0.0
Requires-Dist: oi-harness[all]>=1.0.1
Requires-Dist: oi-memory>=1.0.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: pillow>=10.0
Requires-Dist: playwright>=1.40
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: pydantic<2.14,>=2.6
Requires-Dist: pyjwt>=2.8
Requires-Dist: pypdf>=5.0
Requires-Dist: pypinyin>=0.53
Requires-Dist: python-docx>=1.2.0
Requires-Dist: python-pptx>=1.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.7
Requires-Dist: scalar-fastapi>=1.0
Requires-Dist: segno>=1.6
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: websockets>=13.0
Requires-Dist: xlrd>=2.0.1
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: desktop
Requires-Dist: mss>=9.0; extra == 'desktop'
Requires-Dist: pynput>=1.7; extra == 'desktop'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest-testmon>=2.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: xlwt>=1.3; extra == 'dev'
Provides-Extra: knowledge-ocr
Requires-Dist: onnxruntime>=1.17; extra == 'knowledge-ocr'
Requires-Dist: pymupdf>=1.24; extra == 'knowledge-ocr'
Requires-Dist: rapidocr<4,>=3.4; extra == 'knowledge-ocr'
Provides-Extra: local-embedding
Requires-Dist: fastembed>=0.4; extra == 'local-embedding'
Requires-Dist: huggingface-hub>=0.20; extra == 'local-embedding'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/readme-banner.png" alt="Oi Banner" width="600" />
</p>

<p align="center">
  <strong>A smarter, self-hosted AI assistant — multi-user, multi-agent.</strong>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white" /></a>
  <a href="https://github.com/akankofik-dev/Oi/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green" /></a>
  <a href="https://github.com/akankofik-dev/Oi/releases"><img alt="Version" src="https://img.shields.io/badge/version-1.0-orange" /></a>
  <a href="https://github.com/akankofik-dev/Oi"><img alt="GitHub stars" src="https://img.shields.io/github/stars/akankofik-dev/Oi?style=social" /></a>
  <a href="https://github.com/akankofik-dev/Oi/fork"><img alt="GitHub forks" src="https://img.shields.io/github/forks/akankofik-dev/Oi?style=social" /></a>
</p>

<p align="center">
  <a href="#-highlights">Highlights</a> ·
  <a href="#-overview">Overview</a> ·
  <a href="#-core-technology">Core Technology</a> ·
  <a href="#-features">Features</a> ·
  <a href="#-roadmap">Roadmap</a> ·
  <a href="#-quick-start">Quick Start</a> ·
  <a href="#-contents">Contents</a>
</p>

---

**Oi** is an open-source, self-hosted AI assistant. It's not just a tool — it's a digital life form that can operate in parallel. Through its multi-agent architecture, it builds an intelligent environment that is both independent and collaborative for teams, families, and individuals. Best of all, it runs entirely on your machine — the fully self-hosted design means privacy is never a compromise, while single-process startup makes the powerful web console, CLI, and IM integrations readily accessible.

Chat through the Web Dashboard, Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom, or programmatic HTTP/SSE/WebSocket. Extend capabilities with the **expert library**, **Connectors** (OAuth + MCP), and **ACP** integration for IDE workflows.

## ✨ Highlights

| | Feature | Description |
|---|---------|-------------|
| 👥 | **Multi-user expert team** | One admin, shared household; built-in expert library and expert market — switch specialists per scenario |
| 🤝 | **Expert sharing** | Publish experts and shared skill/sub-agent pools so teammates reuse proven setups instead of rebuilding them |
| 🎭 | **MBTI personas** | 16 personality templates plus an interactive quiz — give each agent a distinct character |
| 🎯 | **AgentTeams** *(Beta)* | A coordinator schedules multiple experts on multi-step work; [details](docs/expert-teams.md) |
| 🔒 | **Security built-in** | JWT multi-user isolation, tool approval, shell command guardrails, and PII redaction — data stays local |
| 🔌 | **Connector ecosystem** | Tencent suite (Docs, Meeting, News, …); OAuth and MCP gateway extend resource boundaries |
| 💾 | **Pluggable workspace backends** | Local disk, Docker sandbox, PostgreSQL, or COS/S3 for agent files — separate from the control-plane DB |
| 🧠 | **Portable memory** | Powered by [Oi Memory](https://github.com/akankofik-dev/oi-memory); memory migrates with the workspace |
| 📚 | **Knowledge base** | RAG over your documents; share corpora within a deployment and ground answers in your private data |
| 🧩 | **Plugins** | Extend Oi with third-party plugins; bundled plugins are seeded and toggled on demand |
| ↔️ | **ACP bidirectional** | `oi acp` for IDE/terminal AI; delegate to OpenCode / Claude Code with permission gates |
| 💻 | **Terminal AI+** | Interactive shell in the browser — AI-assisted command execution and troubleshooting |
| 🌐 | **Browser AI+** | Headless Chromium sessions for web automation, screenshots, and remote browsing |
| 🖥️ | **Remote desktop** | Live screen and input from the dashboard on Linux, Windows, and macOS — remote office work and GUI apps; one-click isolated desktop on headless Linux |
| 🪟 | **Desktop client** | Native Windows / macOS / Linux apps (and FnOS packages) alongside the web dashboard |
| 🏠 | **Self-hosted** | Dashboard, CLI, IM channels, and cron in one `oi run` — all data under `~/.oi/` |

## 📌 Overview

Oi is a self-hosted AI assistant platform for households and small teams. It runs a single process that serves a web dashboard, a CLI, IM channels (Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom, and more), and cron automation — all sharing one control-plane database under `~/.oi/` (SQLite by default; PostgreSQL optional).

> Oi's design goal: keep every conversation, workspace, and credential on your own machine, while giving each user a personal team of specialized agents they can switch between per task.

<details>
<summary>🐾 What can you do with Oi</summary>

- **Personal assistant** — let a dedicated agent write weekly reports, organize notes, and manage your schedule; memory persists with the workspace.
- **Family sharing** — one admin account, the whole household; assign different agents and experts per member; share experts and knowledge bases when useful.
- **Team helper** — AgentTeams or parallel agents, bridging Feishu / DingTalk / WeCom / WeChat to route tasks into group chats.
- **Developer boost** — delegate coding tasks to OpenCode / Claude Code via ACP, or troubleshoot from the terminal with AI assistance.
- **Web automation** — use Browser AI+ and remote desktop for forms, screenshots, and GUI apps.
- **Scheduled tasks** — configure cron in natural language so the agent pushes or runs jobs on time every day.

</details>

## 🧠 Core Technology

| Layer | Technology |
|-------|-----------|
| **Language** | Python 3.12+ |
| **Web framework** | FastAPI + uvicorn |
| **Agent runtime** | [Oi Harness](https://github.com/akankofik-dev/oi-harness) |
| **Gateway** | [Oi Gateway](https://github.com/akankofik-dev/oi-gateway) |
| **Control plane DB** | SQLite (WAL, default) or PostgreSQL (optional) |
| **Frontend** | React 18 + TypeScript + Vite + Ant Design |
| **Scheduling** | APScheduler |
| **ACP** | agent-client-protocol |
| **Build / quality** | hatchling · ruff · mypy · pytest |

Oi is built on the Oi Harness stack — a set of focused runtimes that Oi composes into one process:

- **[Oi Harness](https://github.com/akankofik-dev/oi-harness)** — Agent runtime: model routing, tools, skills, and conversation checkpointing.
- **[Oi Gateway](https://github.com/akankofik-dev/oi-gateway)** — multi-platform IM channel bridge that normalizes incoming messages into a single processing pipeline.
- **[Oi Memory](https://github.com/akankofik-dev/oi-memory)** — hierarchical recall with full-text search, so an agent's memory travels with its workspace.
- **[Oi Browser](https://github.com/akankofik-dev/oi-browser)** — CDP-based browser automation with persistent profiles for web tasks.

Instead of an external queue or message broker, Oi routes every surface — Web UI, IM, and cron — through one in-process `HarnessProcessor`. The result is a single, restart-safe process whose entire state is rebuilt from the control-plane database on boot (local SQLite by default; PostgreSQL optional).

## 🤔 Features

### Server & auth
- Multi-user JWT authentication with admin role
- First-run setup wizard (`oi init`)
- Interactive API docs at `/api/docs` (off by default — set `"enable_api_docs": true` in `config.json` to enable)

### Experts
- Multiple experts per user; each has its own workspace, providers, channels, and cron
- 16 MBTI persona templates + custom system prompt
- Expert library scanned at boot (`infra/agents/experts/library/`); expert market and in-deployment expert sharing
- **AgentTeams** *(Beta)* — coordinator + member experts for multi-step tasks ([docs/expert-teams.md](docs/expert-teams.md))
- Workspace backends (expert files): local disk, Docker sandbox, PostgreSQL, COS/S3, and other remote stores — distinct from the control-plane database

### Channels & automation
- IM channels: Feishu, DingTalk, QQ, WeChat, Telegram, Discord, WeCom, and more
- Proactive cron jobs with natural-language and slash-command triggers
- Unified message processing across Web UI, IM, and cron surfaces

### Surfaces
- **Web dashboard** — chat, experts / teams, connectors, channels, cron, knowledge, plugins, settings
- **Desktop client** — native apps for Windows / macOS / Linux; FnOS packages for NAS
- **CLI** — `oi run`, `oi chats`, `oi acp`, admin commands
- **HTTP/SSE/WebSocket API** — full programmatic access
- **Remote desktop** — dashboard control of the host desktop session

### Knowledge & plugins
- **Knowledge base** — RAG over your documents; optional sharing within the same deployment
- **Plugins** — install and manage third-party plugins (`oi plugin`); bundled plugins are seeded and toggled on demand from the dashboard

### ACP (Agent Client Protocol)

Oi supports ACP in two directions:

1. **Inbound** — external tools use **your** Oi agent
   ```bash
   oi acp --agent main   # stdio ACP server for Zed, OpenCode, …
   ```

2. **Outbound** — Oi delegates to external coding agents
   - Dashboard → **ACP** (`/acp`): configure runners (global per user)
   - Enable **acp_runner** per agent, then delegate in chat

Built-in outbound runners include OpenCode, CodeBuddy, Claude Code, and Codex.

Full setup: **[docs/acp.md](docs/acp.md)**.

## 🧭 Roadmap

Here are our mid-to-long term plans:

**Shipped**
- [x] **Shared resource pool** — a central pool of skills and sub-agents that any user can drop into a new expert without rebuilding from scratch.
- [x] **Expert sharing** — publish your experts to other users in the same deployment, so good configurations are reused instead of recreated.
- [x] **PC client** — native desktop apps for Windows / macOS / Linux alongside the web dashboard and IM channels.

**In progress**
- [ ] **AgentTeams** *(Beta)* — let one coordinator autonomously schedule and orchestrate multiple experts to tackle multi-step tasks.
- [ ] **Mobile client** *(closed beta)* — native mobile apps currently in internal testing.

**Planned**
- [ ] **Browser & terminal polishing** — browser skill *recording* (capture a workflow and replay it as a skill) and a more capable terminal AI assistant.
- [ ] **Self-evolution** — automatically distill everyday conversations into reusable skills, so the assistant grows with you.
- [ ] **Managed Agents** — platform-hosted agent lifecycle (provision, scale, and operate agents without managing the full self-hosted stack yourself).
- [ ] **Project** — project-scoped workspaces that group agents, files, and conversations around a shared goal.
- [ ] **Cloud–edge continuum** — run Oi locally while offloading selected tasks to the cloud, so light work stays on-device and heavier jobs use remote capacity when you need it.
- [ ] **Plugin marketplace** — a curated market to discover, install, and update third-party plugins without leaving Oi.
- [ ] **Conversational control plane** — deepen Oi’s own skills so chat can cover the full dashboard surface: create experts, wire channels, manage knowledge bases, and scaffold plugins end-to-end.

This roadmap may shift as the community grows; treat it as indicative only.

## 🚀 Quick Start

### Prerequisites

- **macOS / Linux / Windows**
- No pre-installed Python required — the installer uses [uv](https://docs.astral.sh/uv/) to provision Python 3.12 in an isolated venv under `~/.oi/`
- A modern multi-core CPU with a few GB of RAM for the process plus model/embedding caches; enough disk for the database, agent workspaces, and document corpora

### 1. Install

> **Scripted install (Ubuntu/Debian, runs as root).** `install.sh` installs
> system packages, builds the dashboard, and registers an `oi.service` systemd
> unit listening on `0.0.0.0:8000`. It changes machine-wide state: it runs as
> root, creates `/etc/systemd/system/oi.service`, and — when `ufw` is present —
> enables the firewall and opens ports 22 and 8000. Read it before running.
>
> ```bash
> git clone https://github.com/akankofik-dev/Oi.git && sudo bash Oi/install.sh
> ```
>
> Re-running it on an existing `/root/Oi` does `git pull --ff-only`, so a
> diverged checkout aborts instead of half-updating. Use the source install
> below for macOS, Windows, or any non-root setup.

**macOS / Linux / Windows** — install from source (recommended):

```bash
git clone -b <branch> https://github.com/akankofik-dev/oi.git
cd Oi
uv sync                 # creates .venv with an isolated Python 3.12
.venv/bin/oi run        # macOS / Linux
```

```powershell
git clone -b <branch> https://github.com/akankofik-dev/oi.git
cd Oi
uv sync                 # creates .venv with an isolated Python 3.12
.\.venv\Scripts\oi.exe run   # Windows
```

`uv` provisions Python 3.12 itself, so no system Python is required. If you
already manage Python, use pip instead:

```bash
pip install -e .        # editable install from the checkout
oi run
```

Both routes install an isolated environment and never touch your system Python.

**Desktop app** (GUI, no terminal) — grab the artifact for your platform from [GitHub Releases](https://github.com/akankofik-dev/Oi/releases/latest):

| Platform | Artifact |
|----------|----------|
| Windows | `Oi-desktop-windows-amd64-<version>.exe` (64-bit) / `Oi-desktop-windows-arm64-<version>.exe` (ARM64) — NSIS installer |
| macOS | `Oi-desktop-darwin-arm64-<version>.dmg` (Apple Silicon) / `Oi-desktop-darwin-amd64-<version>.dmg` (Intel) |
| Linux | `Oi-desktop-linux-amd64-<version>.tar.gz` / `Oi-desktop-linux-arm64-<version>.tar.gz` |
| FnOS NAS | `Oi-fnos-docker-<version>.fpk` (recommended on ARM; amd64/arm64 image) / `Oi-fnos-native-<version>.fpk` (x86_64, no Docker) / `Oi-fnos-native-arm64-<version>.fpk` (ARM64 fallback if no Docker) — install via App Center |

See [desktop/README.md](desktop/README.md) for the desktop shell and [fnos/README.md](fnos/README.md) for the FnOS packaging guide.

> **There is no `oi` distribution on PyPI.** `pip install oi` resolves to an
> unrelated third-party package (`oi` 0.4.2 by Tony Walker,
> <https://github.com/walkr/oi>) and must not be used. The published
> distribution for this code line is `octop`, which is the pre-rebrand release
> line — it installs the top-level package and CLI as `octop`, not `oi`.
> See [docs/installation-audit-issues.md](docs/installation-audit-issues.md).

Install from source instead, as above. Optional extras on a source checkout:

```bash
# local ONNX embedding model cache (Models → Local)
uv sync --extra local-embedding
# Downloads catalog weights under ~/.oi/embedding_models; not chat, not Memory.

# Browser automation: Chromium via the dashboard, or:
uv run python -m playwright install chromium
```

### 2. Initialize

```bash
oi init
```

The interactive wizard creates the SQLite database, JWT secret, and first admin account under `~/.oi/`.

### 3. Run

```bash
# Foreground (API + Web dashboard)
oi run

# Custom host / port
oi run --host 0.0.0.0 --port 8088

# Register as a system service (systemd / launchd / Windows service)
oi service start
```

Open **http://127.0.0.1:8088**. With Docker, the first init generates a random admin password (written to `/data/.oi/credential.txt`) unless `OI_DEFAULT_PASSWORD` is set. Interactive `oi init` / the setup wizard asks you to choose a password (≥8 characters, letters and digits).

### Docker (recommended for production)

```bash
# Build and start
docker compose -f docker/docker-compose.yml up -d

# Or build manually
bash docker/docker_build.sh
docker run -d \
  -p 8088:8088 \
  -v oi-data:/data/.oi \
  -e HOME=/data \
  -e OI_DEFAULT_PASSWORD="<strong-password-or-omit-for-random>" \
  oi:latest
```

Open `http://localhost:8088`. First boot creates the admin account and writes the credentials to `/data/.oi/credential.txt` in the container. With `OI_DEFAULT_PASSWORD` unset a strong random password is generated; a password you set must be ≥8 characters with letters and digits (weak/common passwords are rejected by the app password policy and fall back to a random one). Override the username via `OI_ADMIN_USERNAME`.

> **Password policy:** at least 8 characters with letters and digits.

| Variable | Default | Description |
|----------|---------|-------------|
| `OI_PORT` | `8088` | HTTP listen port |
| `OI_DEFAULT_PASSWORD` | _(unset)_ | First-run admin password (Docker bootstrap). Unset = random password written to `credential.txt` |
| `OI_ADMIN_USERNAME` | `admin` | First-run admin username |
| `OI_DATA` | `~/.oi` | Host data directory (compose bind mount) |

See [`.env.example`](.env.example) for the full list.

## 📑 Contents

- [Highlights](#-highlights)
- [Overview](#-overview)
- [Core Technology](#-core-technology)
- [Features](#-features)
- [Roadmap](#-roadmap)
- [Quick Start](#-quick-start)
- **Deploy & Use**
  - [Install options](#-install-options)
  - [Configuration](#️-configuration)
  - [CLI reference](#-cli-reference)
  - [Web dashboard](#️-web-dashboard)
  - [Data directory](#-data-directory)
- **Architecture & Dev**
  - [Architecture](#️-architecture)
  - [Project layout](#-project-layout)
  - [Development](#️-development)
- **Project Info**
  - [Security & privacy](#-security--privacy)
  - [Contributing](#-contributing)
  - [Changelog](#-changelog)
  - [Related projects](#-related-projects)
  - [License](#-license)

## 📦 Install options

| Method | Platform | Description |
|--------|----------|-------------|
| **Source + uv** | Any | `git clone` → `uv sync` (recommended) |
| **Source + pip** | Any | `git clone` → `pip install -e .` |
| Local script | macOS / Linux | `bash scripts/install.sh` |
| Local script | Windows | `scripts\install.bat` or `install.ps1` |
| Root script | Ubuntu / Debian | `sudo bash install.sh` — systemd unit on `0.0.0.0:8000`, may enable `ufw` |
| Docker | Any | `docker/docker-compose.yml` |

> The root script needs root and changes machine-wide state (systemd unit,
> possibly firewall rules). Prefer the source install unless you are setting up
> a dedicated VPS.
> There is no `oi` distribution on PyPI; `pip install oi` installs an unrelated
> package.

The local scripts provision an isolated environment at `~/.oi/venv` and a
`~/.oi/bin/oi` wrapper — they do not touch system Python.

### Upgrade

`oi update` replaces only the wheel/binary — your `~/.oi/` database, workspaces, secrets, and `config.json` are preserved:

```bash
oi update          # fetch and install the latest oi, then restart the service if one is registered
```

The schema migrates automatically on next boot; run `oi init` only if the setup wizard prompts for a migration. Always back up first (`oi backup`) before a cross-version upgrade.

## ⚙️ Configuration

All runtime state lives in `~/.oi/`. Manage it via CLI or edit files directly.

```bash
# LLM providers and models
oi models
oi provider list

# IM channels
oi channel list
oi channel install

# Skills (per agent)
oi skills list --agent main

# Cron jobs
oi cron list
oi cron create --help

# Users (admin)
oi user list
```

### Supported LLM providers

OpenAI-compatible APIs, DashScope (Qwen), Ollama, and other presets — configure per agent in the dashboard or via `oi provider`.

### Supported channels

| Channel | Credentials |
|---------|-------------|
| **Feishu** | App ID, App Secret |
| **DingTalk** | App Key, App Secret |
| **QQ** | Bot AppID, Token |
| **WeChat** | QR bind / account credentials; [CLI](docs/cli.md) |
| **Telegram** | Bot Token |
| **Discord** | Bot Token; all accessible channels allowed by default, optional channel/DM allowlists; [setup and testing](docs/discord-channel.md) |
| **WeCom** | Corp ID, Agent Secret |
| **Web Dashboard** | Enabled by default |

Other kinds (e.g. Yuanbao, Xiaoyi, MQTT) are available via the gateway — see channel setup in the dashboard or CLI.

## 📖 CLI reference

| Command | Description |
|---------|-------------|
| `oi init` | Bootstrap `~/.oi/` (DB, admin, JWT secret) |
| `oi run` | Start Oi in the foreground |
| `oi service start` | Install and start as a system service |
| `oi service stop` | Stop the system service |
| `oi agent` | Create, list, start/stop agents |
| `oi channel` | Install and manage IM channels |
| `oi chats` | REPL and session management |
| `oi acp` | Stdio ACP server for IDE integration |
| `oi cron` | Manage scheduled tasks |
| `oi models` | Provider presets and model resolution |
| `oi skills` | Enable/disable per-agent skills |
| `oi plugin` | Install and manage third-party plugins |
| `oi backup` | Export / restore backups |
| `oi clean` | Remove CLI state or wipe `~/.oi/` |
| `oi memory list` | List running agents eligible for memory maintenance; no database changes. |
| `oi memory slim [--agent ID]` | Back up and slim SQLite memory through the running host; uses the selected agent or prompts by number. Shows terminal and dashboard progress. [Details](docs/memory-slim.md) |
| `oi memory slim --all` | Sequentially maintain all eligible running agents, with per-agent progress; stops on the first failure. |
| `oi update` | Check for and install updates |

In signed-in dashboard or local CLI chat, `/memory slim` explains maintenance for the current agent;
`/memory slim --all` lists your eligible agents. Add `--confirm` to start after reviewing the impact.
Use `/memory status` for progress/results. Chat stays available until maintenance is confirmed and begins.
External IM maintenance requires verified sender permissions and is not enabled yet.

Full reference: **[docs/cli.md](docs/cli.md)**.

## 🖥️ Web dashboard

After `oi run`, open **http://127.0.0.1:8088**.

<p align="center">
  <img src="docs/assets/readme-chat.png" alt="Oi Web Dashboard" width="800" />
</p>

- **Chat** — real-time conversation with experts and teams
- **Experts** — create experts, pick templates / MBTI personas, share or publish experts, configure providers
- **AgentTeams** *(Beta)* — coordinator + member experts for multi-step work
- **Connectors** — OAuth apps and MCP gateways
- **Channels** — IM platform setup
- **Cron** — visual cron job management
- **Knowledge base** — manage document corpora, semantic retrieval, and in-deployment sharing
- **Plugins** — install, enable, and configure plugins
- **Remote desktop** — live screen and input from the dashboard
- **ACP** — configure outbound coding-agent runners
- **Settings** — users, security, TLS, system

Interactive API docs: **http://127.0.0.1:8088/api/docs** (disabled by default — enable by setting `"enable_api_docs": true` in `config.json`)

## 📁 Data directory

```
~/.oi/                          ← install & data root
├── config.json                    # process config (optional database section)
├── oi.db                       # SQLite — users, agents, channels, cron, …
├── secrets/                       # JWT secret, channel tokens
├── agents/<agent_id>/             # per-agent workspace (SOUL.md, skills, …)
├── security/tool_guard/           # shell command allow/deny rules
├── logs/                          # runtime logs
├── venv/                          # uv-managed Python (installer layout)
└── bin/oi                      # PATH wrapper → venv/bin/oi
```

The control plane can also use PostgreSQL — set `database` in `config.json`, or `OI_DATABASE_*` / the first-run wizard. With PostgreSQL, agent memory reuses the same DSN by default (per-agent schema); to keep file-based memory, set `"memory": { "backend": { "type": "sqlite" } }` in the agent config. See [docs/configuration.md](docs/configuration.md) and [docs/adr/002-database-backends.md](docs/adr/002-database-backends.md).

See [docs/configuration.md](docs/configuration.md) for env vars and `config.json`.

## 🏗️ Architecture

```
OiServer
 ├─ DatabasePool            SQLite (WAL) or PostgreSQL
 ├─ SharedServices       DI root — every repo + config
 ├─ ExpertCatalog        scans agents/experts/library/ at boot
 ├─ UserManager
 │   └─ HarnessAgentManager (per user)
 │       └─ AgentRuntime (per agent)
 │           ├─ HarnessAgent      Agent runtime (oi-harness)
 │           ├─ HarnessProcessor  IM / UI / cron entry point
 │           ├─ ChannelManager    IM connections (oi-gateway)
 │           └─ CronManager       APScheduler
 └─ FastAPI app (uvicorn)
```

Single process. Restart rebuilds state from the control-plane database (local SQLite by default; PostgreSQL optional).

See [docs/architecture.md](docs/architecture.md), [docs/adr/001-single-process-model.md](docs/adr/001-single-process-model.md), and [docs/adr/002-database-backends.md](docs/adr/002-database-backends.md).

## 📁 Project layout

```
src/oi/
  config.py    env-var config
  launch.py    OiServer boot + uvicorn
  infra/       business core (agents, gateway, cron, db, users, …)
  api/         HTTP layer — FastAPI app, routers, JWT, SSE
  cli/         CLI layer — Click commands
  dashboard/   built React SPA (wheel artifact)

dashboard/     frontend source (Vite) — edit here, run make build-frontend

docker/        Docker Compose, entrypoint, build & deploy scripts
tests/         unit/ + integration/
```

## 🛠️ Development

**Prerequisites:** Python 3.12+, Node 18+, [uv](https://docs.astral.sh/uv/)

```bash
# Backend
make install          # pip install -e ".[dev]"
make all              # format-all + lint + typecheck + test (ship bar)

# Frontend (separate terminal)
make dev-frontend     # Vite dev server on :5173 (override with VITE_DEV_PORT)
make build-frontend   # production build → src/oi/dashboard/
cd dashboard && npx tsc -b
```

Individual targets: `make test`, `make lint`, `make typecheck`, `make format`.

## 🔒 Security & privacy

- **Local-first**: Config, chats, workspaces, and credentials live under `~/.oi/` on your machine.
- **Multi-user isolation**: JWT auth with per-user agents and workspaces.
- **PII redaction & tool approval**: sensitive data is redacted before it leaves the workspace, and risky tools or shell commands require explicit approval under the guardrail rules.
- **Tool guardrails**: User-editable shell command rules under `~/.oi/security/tool_guard/`.
- **No vendor lock-in**: Swap LLM providers, storage backends, and channels without rewriting agents.

## 🤝 Contributing

Contributions are welcome:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Run `make all` (backend) or `make check-all` (full stack) before submitting
4. Open a Pull Request

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide. Security issues: [SECURITY.md](SECURITY.md).

Module boundaries and coding conventions: [AGENTS.md](AGENTS.md).

## 📋 Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.

## 🔗 Related projects

| Project | Description |
|---------|-------------|
| [Oi Harness](https://github.com/akankofik-dev/oi-harness) | Agent runtime — model routing, tools, skills, checkpointing |
| [Oi Gateway](https://github.com/akankofik-dev/oi-gateway) | Multi-platform IM channel bridge |
| [Oi Memory](https://github.com/akankofik-dev/oi-memory) | Hierarchical recall and FTS search |
| [Oi Browser](https://github.com/akankofik-dev/oi-browser) | CDP browser automation with persistent profiles |

## 📄 License

This project is licensed under the [MIT License](LICENSE).

## ✨ Contributors

Thanks to all contributors:

<a href="https://github.com/akankofik-dev/Oi/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=akankofik-dev/Oi" />
</a>
