Ailurus OS / Machiavelli

中文文档 / Chinese README →

Local-first AI desktop workbench (a lightweight “desktop OS” experience):

• Electron: desktop shell & OS integrations (windows, tray, dialogs)
• React + Vite: renderer UI
• Python (Flask): local AI/Agent runtime and tool orchestration
• Apps (plugins): pluggable sub-apps under apps/ (frontend + Python backend + capability manifest)

Goal: works out of the box and ecosystem-friendly for third-party app developers.

---

Quick Start (Windows)

Prerequisites

• Node.js LTS (recommended 18/20+)
• Windows PowerShell
• Git (optional)

One-click setup

Run from the repo root:

setup-dev.bat

It will:

1. Run npm install
2. Download and extract Python embeddable into python-embed/ (if missing)
3. Enable import site in python311._pth
4. Install Python deps for the main backend (backend/requirements.txt)

Note: .gitignore excludes python-embed/, so this won’t pollute git changes.

Start dev

npm run dev

• Vite dev server: http://localhost:5173
• Python runtime: http://127.0.0.1:5000

---

LLM Configuration

Configure API Key / Base URL / Model in the UI settings panel.

The Python runtime stores config in the user profile (not in the repo):

• Windows: %APPDATA%\\ailurus-os\\llm_config.json

Note: .gitignore ignores **/llm_config.json to prevent leaking secrets.

---

Architecture Overview

App discovery & install

• Dev mode: reads the repo apps/ directory
• Packaged mode: reads/creates an apps/ directory next to the exe
• Each app is described by ailurus.json:
  • frontend: frontend entry (usually frontend/index.html)
  • backend: Python Flask backend entry (usually backend/app.py)
  • capabilities: agent-visible capabilities (name/description/keywords/schema)

Runtime & routing

• Electron starts the main Python runtime (Flask on port 5000)
• When an app is launched/preloaded:
  • Electron asks the main runtime to load the app backend via /api/tools/<tool_id>/load
  • The main runtime proxies requests from /<tool_id>/api/... to that app’s Flask app

Agent execution

• Main runtime endpoint: /api/agent/execute
  • routes and orchestrates based on capabilities
  • dispatches to /<tool_id>/api/agent/handle
• Each app can implement its own agent handler:
  • parse parameters (optionally using LLM)
  • run internal APIs
  • return { text, data }

---

Developing a Plugin App

Minimal structure

apps/my-app/
	ailurus.json
	frontend/
		index.html
		main.js
		style.css
		i18n.json            (optional)
	backend/
		app.py
		requirements.txt     (optional)
	pack_app.py            (optional, recommended)
	README.md              (optional)

ailurus.json (practical fields)

• name: display name
• version: semver recommended
• frontend: frontend entry file
• backend: backend entry file (must expose app = Flask(...))
• capabilities[]:
  • name: capability name
  • description: what it does
  • keywords: routing keywords
  • api: { method, endpoint, schema } (JSON Schema)

Backend contract

Your backend/app.py should:

• export app = Flask(__name__)
• implement routes referenced by capabilities[].api.endpoint
• (for Agent integration) implement /api/agent/handle

Optional: export shutdown(); the main runtime will try to call it on unload for cleanup.

Packaging & distribution

Example apps include pack_app.py to produce a .ail package:

cd apps/chron
python pack_app.py

Then import the .ail file in the UI.

---

Build & Release

npm run package

Notes:

• Electron-builder packages dist/, electron/, backend/
• Windows builds bundle python-embed/ via extraFiles

---

.gitignore Notes

The repo ignores (highlights):

• python-embed/ (embeddable Python, downloaded locally)
• release/, dist/, node_modules/ (build outputs)
• **/llm_config.json (secrets)

---

License

MIT