What is moeru-ai/airi?
Overview
Overview: Meet Grok Companion, a privacy-first, self-hosted AI partner you fully control.
- moeru-ai/airi is an open-source, self-hosted project that delivers Grok Companion — a suite of AI personalities designed for real-time interaction.
- It enables real-time voice chat and playful, AI-driven experiences in games such as Minecraft and Factorio.
- It runs on Web, macOS, and Windows, bringing accessibility across devices.
- The goal is to provide a personal, controllable AI companion with a playful, waifu-inspired character, built for privacy and local hosting.
How moeru-ai/airi works
Technical overview
Take control with a self-hosted, containerized solution that runs on your terms—locally or on your server—delivering AI personalities, real-time voice interactions, and seamless game integration.
- Runs as a containerized, self-hosted application you control locally or on your own server.
- The Grok Companion container hosts AI personalities and enables real-time voice interactions.
- Includes hooks for popular games—Minecraft and Factorio—that enable in-game AI interactions.
- A web-based UI plus desktop clients let you access the system from any supported platform.
Getting Started with moeru-ai/airi
Prerequisites
Prerequisites: this script helps you set up a clean Python environment and install the moeru-ai/airi package from GitHub. It creates a virtual environment, upgrades pip, installs airi, and prompts you to set your API key before you start building tasks.
# Prerequisites: Setup a clean Python environment and install moeru-ai/airi.
# This script creates a virtual environment, installs Airi from GitHub, and prompts you to set an API key.
import sys
import os
import subprocess
from pathlib import Path
def check_python():
if sys.version_info < (3, 8):
raise SystemExit("Python 3.8+ is required.")
def run(cmd: str):
print(f"> {cmd}")
rc = subprocess.call(cmd, shell=True)
if rc != 0:
raise SystemExit(rc)
def setup():
check_python()
venv_dir = Path(".venv_airi")
if not venv_dir.exists():
# create venv
run(f"{sys.executable} -m venv {venv_dir}")
# path to pip inside venv
bin_dir = "Scripts" if os.name == "nt" else "bin"
pip = venv_dir / bin_dir / "pip"
run(f"{pip} install --upgrade pip")
run(f"{pip} install git+https://github.com/moeru-ai/airi.git")
print("\nPrerequisites completed. Set AIRI_API_KEY in your environment, e.g.:")
print(" export AIRI_API_KEY=your_key # Unix")
print(" set AIRI_API_KEY=your_key # Windows")
print("Then you can run a basic Airi task in your code, e.g.: from airi import Airi\n")
if __name__ == "__main__":
setup()Install and Run
Here’s a compact Python script that automates the “Install and Run” flow for moeru-ai/airi. It clones the repo, creates a virtual environment, installs dependencies, and then runs the CLI to show a quick verification (help output). You can modify the last step to start an interactive session once installed.
import os
import sys
import subprocess
REPO = "https://github.com/moeru-ai/airi.git"
DIR = "airi"
def run(cmd, cwd=None):
print(f"+ {cmd}")
subprocess.run(cmd, shell=True, check=True, cwd=cwd)
def main():
# 1) Clone the repo if missing
if not os.path.isdir(DIR):
run(f"git clone {REPO} {DIR}")
# 2) Create a virtual environment inside the repo
venv = os.path.join(DIR, "venv")
if not os.path.isdir(venv):
run(f"{sys.executable} -m venv {venv}")
# 3) Pick the python binary inside the venv
if os.name == "nt":
python_bin = os.path.join(venv, "Scripts", "python.exe")
else:
python_bin = os.path.join(venv, "bin", "python")
# 4) Upgrade pip and install dependencies
run(f"{python_bin} -m pip install --upgrade pip")
run(f"{python_bin} -m pip install -r requirements.txt", cwd=DIR)
# 5) Run the CLI to verify (prints help)
run(f"{python_bin} -m airi --help", cwd=DIR)
print("\nDone. To run interactively, try:")
print(" cd airi && /bin/python -m airi (or the entrypoint if installed)")
if __name__ == "__main__":
main() First-time Configuration
This simple Python script creates a basic, non-interactive first-time configuration for moeru-ai/airi by writing a config file at ~/.airi/config.json. It reads the API key from the AIRI_API_KEY environment variable (or prompts once), and stores the workspace and default model. Later, the Airi library can read this file to authenticate and set defaults automatically.
import json
import os
from pathlib import Path
def write_config():
home = Path.home()
config_dir = home / ".airi"
config_dir.mkdir(parents=True, exist_ok=True)
config_path = config_dir / "config.json"
# Get API key from environment or prompt the user
api_key = os.environ.get("AIRI_API_KEY")
if not api_key:
api_key = input("Enter your moeru-ai Airi API key: ").strip()
if not api_key:
raise SystemExit("API key is required. Set AIRI_API_KEY or provide it when prompted.")
# Optional: allow overriding via environment variables
workspace = os.environ.get("AIRI_WORKSPACE") or "personal"
model = os.environ.get("AIRI_MODEL") or "gpt-4"
config = {
"api_key": api_key,
"workspace": workspace,
"model": model
}
with open(config_path, "w") as f:
json.dump(config, f, indent=2)
print(f"Wrote Airi config to {config_path}")
if __name__ == "__main__":
write_config()
Features and capabilities
Real-time voice chat
Chat with AI personalities in real time—speech flows as naturally as a live conversation, with minimal latency between your words and the AI’s reply. It’s built for fluid, spoken interaction, not slow text messages or waiting for a response.
- Low-latency voice communication between you and AI personalities
- Audio is transmitted with real-time communication tech (such as WebRTC) to minimize delay.
- Efficient codecs (like Opus) and network optimizations reduce jitter and packet loss, helping you hear AI responses quickly.
- End-to-end latency stays low enough to support natural back-and-forth dialogue in typical network conditions.
- Supports multiple voice channels and server-wide interactions
- Multiple voice channels let you create separate rooms or topics (for example, “Frontend Bot,” “QA Bot,” or “Team Standup”) to keep conversations organized.
- Server-wide interactions enable audio to flow across channels for announcements, cross-topic chats, or events, while respecting permissions and moderation rules.
Game integrations
NPCs and AI teammates are changing how you play, adding smart helpers, traders, and guides right into the action. Here’s a clear look at how this works in popular ecosystems like Minecraft and Factorio.
- Minecraft and Factorio rely on plugins and mods to bring NPCs into the action.
- In Minecraft, server plugins and mods can add non-player characters (NPCs) that move, interact with players, trade items, or join quests.
- In Factorio, mods introduce NPCs such as traders or allies who participate in scenarios, campaigns, or cooperative play.
- AI characters can assist, converse, or guide gameplay in supported mod ecosystems.
- These AI-driven characters offer tips, explain game systems, explore strategies, or walk players through tutorials and missions within selected modpacks or custom worlds.
Cross-platform access
Access your tools from any device or OS with a streamlined, secure workflow for developers.
- Web UI runs in any browser. Desktop clients are available for macOS and Windows.
- All data stays on your host; optional cloud backups are available if you enable them.
Open-source and community
Open source thrives on collaboration—contribute, share, and shape the future together.
- Contributions via forks and pull requests (PRs). Teams fork the project, develop changes in their own copy, and submit a PR for review and merge into the main project. This workflow streamlines collaboration and keeps the project inclusive and transparent.
- Permissive licenses to promote experimentation and reuse. Common choices like MIT, Apache-2.0, and BSD impose few restrictions on reuse and redistribution, enabling you to experiment with the code, build on it, and share improvements—even in commercial or proprietary contexts.
Contribute, safety and community guidelines
How to contribute
Ready to contribute? You’ll learn, add value, and gain visibility in the open‑source ecosystem. Here’s a clear, practical path to get started.
- Star, fork, and submit pull requests with clear changes.
- Star the repository to show interest and help others discover it.
- Fork the repository to your own account so you can work independently.
- Create a new branch for your work, implement the changes, and write a concise, descriptive commit message.
- Submit a pull request with a concise summary of the changes, the motivation, and how to test them.
- Join discussions in the issue tracker and engage with the community channels.
- Comment on relevant issues to ask questions, provide context, or propose fixes.
- Participate in the project’s community channels (as directed by the maintainers) to stay aligned and get help.
- Follow the project’s code of conduct and contribution guidelines.
- Read and follow the code of conduct to keep interactions respectful and inclusive.
- Review the contribution guidelines for PR formatting, testing expectations, and how to report issues.
Licensing and safety
Take control of your open-source projects by prioritizing licensing and security from the start. This guide shows you how to verify license details in a repository and host applications safely while protecting user privacy.
- Open-source license details included in the repository
- Look for a LICENSE, LICENSE.txt, or LICENSE.md at the repository root. It defines what you can do with the code and any obligations when using or distributing it.
- Some projects also include a NOTICE file with attribution requirements for certain licenses.
- Check license metadata in manifests (for example, package manifests or build files) for SPDX identifiers such as SPDX-License-Identifier: MIT. This helps identify the license and its version quickly.
- Be aware of multiple licenses or dual licensing. You must comply with all applicable licenses for the parts you reuse.
- Understand the difference between copyleft licenses (which may require sharing modifications) and permissive licenses (which are more flexible but may require attribution or patent terms).
- Note any attribution and notice requirements, especially when redistributing or hosting services that use the code.
- Keep license information up to date when upgrading dependencies or forking projects, as licenses or terms can change over time.
- Best practices for safe, local hosting and protecting user privacy
- Host on hardware you control within a trusted network, and minimize exposure to the public internet. Use firewalls and least-privilege network access.
- Isolate services (containers or virtual machines) and apply the principle of least privilege for users and processes.
- Keep software up to date with security patches and perform regular vulnerability checks on dependencies.
- Use reproducible builds and verify checksums or signatures for dependencies and container images. Consider signing artifacts where possible.
- Protect data in transit with encryption (TLS) and protect data at rest with strong storage encryption and proper key management. Avoid hard-coding credentials.
- Minimize data collection: collect only what you need, disable or provide opt-out options for telemetry, and provide a clear privacy notice.
- Implement robust access controls: strong authentication (prefer multi-factor), authorization checks, and comprehensive audit logs.
- Limit exposure of personal data: avoid logging PII where possible, and implement redaction or anonymization when logging is necessary. Define data retention and deletion policies.
- Include a privacy policy and data-handling practices in your documentation, and consider applicable laws such as GDPR or CCPA if you process user data.
- Document deployment and privacy practices so users understand how their data is used in local installations and what rights they have.
| License details in repo | Where to find license text, how to read it, and what to check (attribution, copyleft, version). |
| Local hosting and privacy | Practical steps for safe hosting and protecting user data (network, access, encryption, data minimization, compliance). |
