### Initialize and Start Development Server

Source: https://github.com/moeru-ai/airi/blob/main/README.md

Install dependencies and start the development server for the browser version.

```shell
pnpm i
pnpm dev
```

```shell
pnpm dev
```

--------------------------------

### Install Dependencies and Setup Environment

Source: https://github.com/moeru-ai/airi/blob/main/services/twitter-services/docs/architecture-20250304.md

Commands to install project dependencies and set up the local environment variables for development. Ensure to add your BrowserBase API key and Twitter credentials.

```bash
# Install dependencies
npm install

# Set environment variables
cp .env.example .env
# Edit .env to add BrowserBase API key and Twitter credentials (optional)
```

--------------------------------

### Setup and Run Local Update Server

Source: https://github.com/moeru-ai/airi/blob/main/apps/stage-tamagotchi/scripts/update-test/README.md

Commands to set up the local fixture directories, generate update manifests, and start the HTTP server for testing.

```bash
bash apps/stage-tamagotchi/scripts/update-test/setup.sh
pnpm -F @proj-airi/stage-tamagotchi update-test:generate \
  --root scripts/update-test/fixtures/server \
  --channel stable \
  --target aarch64-apple-darwin \
  --version 9.9.9-update-test.1
pnpm -F @proj-airi/stage-tamagotchi update-test:server \
  --port 8787 \
  --root scripts/update-test/fixtures/server
```

--------------------------------

### Install @proj-airi/server-sdk

Source: https://github.com/moeru-ai/airi/blob/main/packages/server-sdk/README.md

Install the server SDK using your preferred package manager.

```shell
ni @proj-airi/server-sdk -D # from @antfu/ni, can be installed via `npm i -g @antfu/ni`
```

```shell
pnpm i @proj-airi/server-sdk -D
```

```shell
yarn i @proj-airi/server-sdk -D
```

```shell
npm i @proj-airi/server-sdk -D
```

--------------------------------

### Install @proj-airi/ui

Source: https://github.com/moeru-ai/airi/blob/main/packages/ui/README.md

Install the @proj-airi/ui library using your preferred package manager.

```shell
ni @proj-airi/ui -D
```

```shell
pnpm i @proj-airi/ui -D
```

```shell
yarn i @proj-airi/ui -D
```

```shell
npm i @proj-airi/ui -D
```

--------------------------------

### Install Scoop and Tools (Windows)

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/index.md

Installs Scoop, Git, Node.js, and Rustup on Windows. Ensure to install Windows SDK and C++ build tools with Visual Studio.

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
```

```powershell
scoop install git nodejs rustup

# For Rust dependencies
# Not required if you are not going to develop on either crates or apps/tamagotchi
scoop install main/rust-msvc
# Rust & Windows specific
rustup toolchain install stable-x86_64-pc-windows-msvc
rustup default stable-x86_64-pc-windows-msvc
```

--------------------------------

### Start Documentation Server

Source: https://github.com/moeru-ai/airi/blob/main/README.md

Launch the local development server for the documentation site.

```shell
pnpm dev:docs
```

--------------------------------

### Example .env.local Configuration

Source: https://github.com/moeru-ai/airi/blob/main/services/telegram-bot/README.md

An example of how to fill in the .env.local file with specific credentials and API endpoints. Ensure you replace placeholders with your actual tokens and URLs.

```shell
DATABASE_URL=postgres://postgres:123456@localhost:5433/postgres
TELEGRAM_BOT_TOKEN='<Bot ID>:<Token>' # get one from @BotFather

LLM_API_BASE_URL='https://openrouter.ai/api/v1/' # if you use OpenRouter too
LLM_API_KEY='sk-or-v1-<token>'
LLM_MODEL='deepseek/deepseek-chat-v3-0324:free'
LLM_RESPONSE_LANGUAGE='English'

LLM_VISION_API_BASE_URL='https://openrouter.ai/api/v1/'
LLM_VISION_API_KEY='sk-or-v1-<token>'
LLM_VISION_MODEL='openai/gpt-4o' # as long as the model supports image input

EMBEDDING_API_BASE_URL='http://localhost:11434/v1/' # ollama
EMBEDDING_API_KEY=''
EMBEDDING_MODEL='nomic-embed-text' # embedding model
EMBEDDING_DIMENSION='768' # must set
```

--------------------------------

### Install Desktop Dependencies (Linux)

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/index.md

Installs necessary development libraries for the desktop version on Linux using apt.

```shell
sudo apt install \
   libssl-dev \
   libglib2.0-dev \
   libgtk-3-dev \
   libjavascriptcoregtk-4.1-dev \
   libwebkit2gtk-4.1-dev
```

--------------------------------

### Start Development Server

Source: https://github.com/moeru-ai/airi/blob/main/apps/server/docs/ai-context/verifications/account-deletion.md

Boots the server to verify that the user deletion service and authentication dependencies resolve correctly.

```sh
pnpm -F @proj-airi/server dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/moeru-ai/airi/blob/main/apps/stage-pocket/android/README.md

Install project dependencies from the repository root using pnpm.

```bash
pnpm install
```

--------------------------------

### Install @proj-airi/server-shared

Source: https://github.com/moeru-ai/airi/blob/main/packages/server-shared/README.md

Install the shared server package using your preferred package manager.

```shell
ni @proj-airi/server-shared -D # from @antfu/ni, can be installed via `npm i -g @antfu/ni`
```

```shell
pnpm i @proj-airi/server-shared -D
```

```shell
yarn i @proj-airi/server-shared -D
```

```shell
npm i @proj-airi/server-shared -D
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/moeru-ai/airi/blob/main/services/telegram-bot/README.md

Clone the アイリ repository and install project dependencies using pnpm. Ensure you have pnpm installed globally.

```shell
git clone git@github.com:moeru-ai/airi.git
pnpm i
pnpm run build:packages
```

--------------------------------

### Initialize Client and Server

Source: https://github.com/moeru-ai/airi/blob/main/packages/better-ws/README.md

Basic setup for a client with reconnection policy and a server with peer management.

```ts
import { createClient } from '@proj-airi/better-ws'
import { createServer } from '@proj-airi/better-ws/server'

const client = createClient({
  url: 'ws://localhost:3000/ws',
  // Reconnect is enabled by default; pass an object to customize the policy.
  reconnect: {
    retries: Number.POSITIVE_INFINITY,
    delay: attempt => Math.min(1000 * 2 ** (attempt - 1), 30_000),
  },
})

await client.connect()
client.send('hello')

const server = createServer<string>()

server.onMessage(({ server, message }) => {
  server.broadcast(message)
})

const peer = server.accept({
  id: 'peer-1',
  send(message) {
    console.info('send to runtime', message)
    return true
  },
})

peer.receive('hello')
```

--------------------------------

### Start Minecraft Bot Service (Repo Root)

Source: https://github.com/moeru-ai/airi/blob/main/services/minecraft/README.md

Start the Minecraft bot service using pnpm from the repository root.

```bash
pnpm -F @proj-airi/minecraft-bot dev
```

--------------------------------

### Install @proj-airi/server-sdk-shared

Source: https://github.com/moeru-ai/airi/blob/main/packages/server-sdk-shared/README.md

Install the package as a development dependency using npm or pnpm.

```shell
ni @proj-airi/server-sdk-shared -D
pnpm i @proj-airi/server-sdk-shared -D
```

--------------------------------

### Install ni Package Manager

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/index.md

Installs @antfu/ni globally for simplified package management commands like install, run, and test.

```shell
corepack enable
npm i -g @antfu/ni
```

--------------------------------

### Copy Environment File

Source: https://github.com/moeru-ai/airi/blob/main/services/discord-bot/README.md

Copy the example environment file to create a local configuration file.

```shell
cd services/discord-bot
cp .env .env.local
```

--------------------------------

### Install Workspace Dependencies

Source: https://github.com/moeru-ai/airi/blob/main/services/minecraft/README.md

Run this command from the repo root to install all necessary project dependencies.

```bash
pnpm i
```

--------------------------------

### Install Git and Node.js (macOS)

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/index.md

Installs Git and Node.js using Homebrew. This is a prerequisite for package management.

```shell
brew install git node
```

--------------------------------

### Start Mobile Version

Source: https://github.com/moeru-ai/airi/blob/main/README.md

Launch the development server for the iOS capacitor target.

```shell
pnpm dev:pocket:ios --target <DEVICE_ID_OR_SIMULATOR_NAME>
# Or
CAPACITOR_DEVICE_ID_IOS=<DEVICE_ID_OR_SIMULATOR_NAME> pnpm dev:pocket:ios
```

--------------------------------

### Install VNC Server

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/blog/DevLog-2025.08.26/index.md

Installs the x11vnc package, which is necessary for VNC functionality.

```bash
sudo apt install -y x11vnc
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/moeru-ai/airi/blob/main/services/discord-bot/README.md

Clone the project repository and install the necessary dependencies using pnpm.

```shell
git clone git@github.com:moeru-ai/airi.git
pnpm i
```

--------------------------------

### Start the Discord Bot

Source: https://github.com/moeru-ai/airi/blob/main/services/discord-bot/README.md

Run the command to start the Discord bot after configuring the environment variables.

```shell
pnpm run -F @proj-airi/discord-bot start
```

--------------------------------

### Start Desktop Version

Source: https://github.com/moeru-ai/airi/blob/main/README.md

Launch the development server for the Tamagotchi desktop version.

```shell
pnpm dev:tamagotchi
```

--------------------------------

### Run Desktop as Root

Source: https://github.com/moeru-ai/airi/blob/main/README.md

Start the desktop version with root privileges for wireless connection support.

```shell
sudo pnpm dev:tamagotchi
```

--------------------------------

### Start Satori Bot using ni

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/services/satori.md

An alternative method to start the Satori Bot in development mode using the ni command-line tool. This is a shortcut if you use [@antfu/ni](https://github.com/antfu-collective/ni).

```shell
nr -F @proj-airi/satori-bot dev
```

--------------------------------

### Start Development Server

Source: https://github.com/moeru-ai/airi/blob/main/services/twitter-services/docs/architecture-20250304.md

Commands to start the development server in standard mode or with the MCP development server enabled. These commands are used for local development and testing.

```bash
# Development mode startup
npm run dev        # Standard mode
npm run dev:mcp    # MCP development server mode
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/index.md

Installs project dependencies using pnpm and fetches Rust dependencies if needed.

```shell
corepack enable
pnpm install

# For Rust dependencies
# Not required if you are not going to develop on either crates or apps/tamagotchi
cargo fetch
```

--------------------------------

### Start Android Emulator from Command Line

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/blog/DevLog-2025.04.22/index.md

This bash command shows how to launch an Android emulator directly from the command line, which can help reduce memory usage compared to starting it via Android Studio.

```bash
emulator -avd Pixel_6_Pro_API_34
```

--------------------------------

### Install xsAI Transformers.js

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/blog/DevLog-2025.05.16/index.md

Install the xsAI Transformers.js library via npm. This library enables WebGPU powered model inference and serving with workers.

```bash
npm install xsai-transformers
```

--------------------------------

### Install Websockify and NoVNC

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/blog/DevLog-2025.08.26/index.md

Installs websockify for VNC to HTTP protocol conversion and novnc for a web-based VNC client interface.

```bash
sudo apt install -y websockify novnc
```

--------------------------------

### Documenting Normalizers

Source: https://github.com/moeru-ai/airi/blob/main/AGENTS.md

Use this format to provide before and after examples for functions that normalize inputs or outputs.

```ts
/**
 * Normalizes <target>.
 *
 * Before:
 * - "ExampleInput"
 *
 * After:
 * - "example-output"
 */
```

--------------------------------

### Start Database and Telegram Bot

Source: https://github.com/moeru-ai/airi/blob/main/services/telegram-bot/README.md

Start the database using Docker Compose and then run the Telegram bot using pnpm. Ensure Docker is running before executing these commands.

```shell
docker compose up -d
pnpm run -F @proj-airi/telegram-bot start
```

--------------------------------

### Start local observability infrastructure

Source: https://github.com/moeru-ai/airi/blob/main/apps/server/README.md

Launch the OpenTelemetry stack using the provided Docker Compose configuration.

```yaml
docker compose -f apps/server/docker-compose.otel.yml up -d
```

--------------------------------

### Run Telegram Bot

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/services/telegram.md

Start the Telegram bot application after setting up the environment and database.

```shell
pnpm -F @proj-airi/telegram-bot start
```

--------------------------------

### Get Recent Logs in Minecraft Debug

Source: https://github.com/moeru-ai/airi/blob/main/services/minecraft/codex-skills/minecraft-debug-mcp/references/mcp-surface.md

Retrieves recent LLM log entries. Start with small limits for efficiency.

```typescript
get_logs(limit?: number)
```

--------------------------------

### Define Chatbot Actions

Source: https://github.com/moeru-ai/airi/blob/main/services/telegram-bot/src/prompts/system-ticking-v1.velin.md

Defines a list of available actions for a chatbot, including their names, descriptions, and example usage. This setup is crucial for enabling the chatbot to interact with users and perform specific tasks.

```javascript
const actions = [
  {
    name: 'list_chats',
    description: 'List all available chats, best to do before you want to send a message to a chat.',
    example: { action: 'list_chats', reason: 'Haven\'t heard from this chat for a while, I want to check it' },
  },
  {
    name: 'send_message',
    description: ''
      + 'Send a message to a specific chat group.If you want to express anything to anyone or your friends'
      + 'in group, you can use this action.'
      + 'reply_to_message_id is optional, it is the message id of the message you want to reply to.'
      + `${props.responseLanguage ? `The language of the sending message should be in ${props.responseLanguage}.` : ''}`,
    example: { action: 'send_message', content: '<content>', chatId: '123123', reply_to_message_id: '151' },
  },
  {
    name: 'send_sticker',
    description: 'Send a sticker to a specific chat group. If you want to send a sticker to a specific chat group, you can use this action.',
    example: { action: 'send_sticker', fileId: '123123', chatId: '123123', reason: 'I want to express my feeling of...' },
  },
  {
    name: 'list_stickers',
    description: 'List all the available stickers and recent sent stickers.',
    example: { action: 'list_stickers', reason: 'I want to see all the stickers I can use' },
  },
  {
    name: 'read_unread_messages',
    description: 'Read unread messages from a specific chat group. If you want to read the unread messages from a specific chat group, you can use this action.',
    example: { action: 'read_unread_messages', chatId: '123123', reason: 'I want to catch up on the conversation' },
  },
  {
    name: 'continue',
    description: 'Continue the current task, which means to keep your current state unchanged, I\'ll ask you again in (1 minute later).',
    example: { action: 'continue', reason: 'I want to continue because I need more time to think.' },
  },
  {
    name: 'break',
    description: 'Take a break, which means to clear out any existing memories, and I\'ll ask you again in (1 minute later).',
    example: { action: 'break', reason: 'I need a break to recharge.' },
  },
  {
    name: 'sleep',
    description: 'Sleep, which means to clear out ongoing tasks, and clear out the working memory, and I\'ll ask you again in next tick (1 minute later).',
    example: { action: 'sleep', reason: 'It\'s being a while since I am active, sleep for a while' },
  },
  {
    name: 'come_up_ideas',
    description: 'By giving references to contexts, come up ideas to record in long-term memory.',
    example: { action: 'come_up_ideas', ideas: ['I want to tell everyone a story of myself', 'I want to google how to make a AI like me'] },
  },
  {
    name: 'come_up_goals',
    description: 'By giving references to contexts, come up goals with deadline and priority to record in long-term memory.',
    example: { action: 'come_up_goals', goals: [{ text: 'Learn to play Minecraft', deadline: '2025-05-01 23:59:59', priority: 6 }, { text: 'Learn anime of this season', deadline: '2025-01-08 23:59:59', priority: 9 }] },
  },
]

```

--------------------------------

### AIRI Local macOS MCP Configuration

Source: https://github.com/moeru-ai/airi/blob/main/services/computer-use-mcp/README.md

Example JSON configuration for starting the computer-use-mcp service locally on macOS via PNPM. It specifies the command, arguments, working directory, and environment variables for execution.

```json
{
  "mcpServers": {
    "computer_use": {
      "command": "pnpm",
      "args": [
        "-F",
        "@proj-airi/computer-use-mcp",
        "start"
      ],
      "cwd": "/path/to/your/airi/repo",
      "env": {
        "COMPUTER_USE_EXECUTOR": "macos-local",
        "COMPUTER_USE_APPROVAL_MODE": "actions",
        "COMPUTER_USE_OPENABLE_APPS": "Terminal,Cursor,Google Chrome"
      }
    }
  }
}
```

--------------------------------

### Execute cap-vite examples

Source: https://github.com/moeru-ai/airi/blob/main/packages/cap-vite/README.md

Common usage patterns for running iOS and Android builds with specific targets and environment variables.

```bash
pnpm exec cap-vite -- ios --target <DEVICE_ID_OR_SIMULATOR_NAME>
pnpm exec cap-vite -- --host 0.0.0.0 --port 5173 -- android --target <DEVICE_ID_OR_SIMULATOR_NAME> --flavor release
CAPACITOR_DEVICE_ID_IOS=<DEVICE_ID_OR_SIMULATOR_NAME> pnpm exec cap-vite -- ios
pnpm -F @proj-airi/stage-pocket run dev:ios -- --target <DEVICE_ID_OR_SIMULATOR_NAME>
```

--------------------------------

### Run Documentation Site Locally with @antfu/ni

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/docs.md

If you are using [@antfu/ni](https://github.com/antfu-collective/ni), you can use this command as a shortcut to start the documentation site in development mode.

```shell
nr dev:docs
```

--------------------------------

### Run Web UI Development Server with ni

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/webui.md

If you are using [@antfu/ni](https://github.com/antfu-collective/ni), you can use this command as a shortcut to start the development server.

```shell
nr dev
```

--------------------------------

### Install pgvector Extension

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/blog/DevLog-2025.04.06/index.md

SQL commands to install the standard pgvector extension.

```sql
DROP EXTENSION IF EXISTS vector;
CREATE EXTENSION vector;
```

--------------------------------

### Run Development Server

Source: https://github.com/moeru-ai/airi/blob/main/plugins/airi-plugin-web-extension/README.md

Use this command to start the development server for the AIRI web extension. Load the unpacked extension from the specified directory in your browser.

```bash
pnpm -F @proj-airi/airi-plugin-web-extension dev
```

--------------------------------

### Install dependencies

Source: https://github.com/moeru-ai/airi/blob/main/services/computer-use-mcp/validation/browser-repair-contract.md

Installs project dependencies while skipping lifecycle scripts for local verification.

```sh
pnpm install --ignore-scripts --frozen-lockfile
```

--------------------------------

### Install and Configure UnoCSS

Source: https://github.com/moeru-ai/airi/blob/main/packages/ui/README.md

Install UnoCSS and configure it with Attributify Mode in your uno.config.ts file.

```shell
pnpm i -D unocss
```

```typescript
import { defineConfig, presetAttributify } from 'unocss'

export default defineConfig({
  presets: [
    presetAttributify(),
    // ...your other presets
  ],
})
```

--------------------------------

### Connect and Handle Events with Server SDK

Source: https://github.com/moeru-ai/airi/blob/main/packages/server-sdk/README.md

Initialize the client, establish a connection, and set up event listeners. The `connect()` method now resolves when the client is fully ready, including successful authentication and module announcement.

```typescript
import { Client } from '@proj-airi/server-sdk'

const client = new Client({
  name: 'your airi plugin',
  autoConnect: false,
})

await client.connect()

client.onEvent('input:text', async (event) => {
  console.info(event.data.text)
})
```

--------------------------------

### Initialize a minimal mock API server

Source: https://github.com/moeru-ai/airi/blob/main/docs/solutions/developer-experience/agent-browser-mock-api-verification.md

Use a one-line Node.js command to serve required API endpoints for local frontend development.

```bash
node -e "const http=require('http'); /* serve /api/admin/me and required page APIs */"
```

--------------------------------

### Create and Configure .env.local File

Source: https://github.com/moeru-ai/airi/blob/main/services/telegram-bot/README.md

Copy the .env file to .env.local and fill in the required credentials for database, Telegram bot token, and LLM/embedding API configurations.

```shell
cd services/telegram-bot
cp .env .env.local
```

--------------------------------

### Install AIRI via Package Managers

Source: https://github.com/moeru-ai/airi/blob/main/README.md

Use these commands to install the AIRI application on Windows or macOS systems.

```powershell
winget install MoeruAI.AIRI
```

```powershell
scoop bucket add airi https://github.com/moeru-ai/airi
scoop install airi/airi
```

```sh
brew install --cask airi
```

--------------------------------

### Install pnpm via Corepack (Windows)

Source: https://github.com/moeru-ai/airi/blob/main/docs/content/en/docs/contributing/index.md

Activates Corepack and installs the latest version of pnpm for package management.

```powershell
corepack enable
corepack prepare pnpm@latest --activate
```

--------------------------------

### Run with Nix

Source: https://github.com/moeru-ai/airi/blob/main/README.md

Execute the project using Nix flakes.

```shell
nix run github:moeru-ai/airi
```

--------------------------------

### Data Plane Message Examples

Source: https://github.com/moeru-ai/airi/blob/main/packages/plugin-sdk/docs/design/architecture.md

Examples of typical data messages for high-throughput streams like audio, vision, and telemetry.

```text
- data:context:update
- data:vision:frame
- data:audio:stream
- data:transcript
- data:character:output
```

--------------------------------

### Control Plane Message Examples

Source: https://github.com/moeru-ai/airi/blob/main/packages/plugin-sdk/docs/design/architecture.md

Examples of typical control messages used for plugin lifecycle, configuration, and UI contributions.

```text
- control:hello
- control:announce
- control:plugin:register
- control:plugin:config:get
- control:plugin:config:set
- control:capability:grant
- control:capability:revoke
- control:ui:register
```