Skip to content

Developer Onboarding: Getting Started with AICO

This guide is for developers and contributors.

Here you'll find everything you need to set up your development environment, understand the project structure, and start contributing.

Project Overview

AICO is an open-source, local-first AI companion designed to be emotionally present, embodied, and proactive. The project is modular, privacy-first, and extensible, with contributions welcome from developers, designers, researchers, and more.

Quick Start (Developers)

From a fresh repo clone, the canonical way to bootstrap a working local stack (single Docker host) is:

# Initialize repo-local config templates (idempotent)
uv run --project cli aico config init

# Provision infra + schema + tenant + admin/owner user (idempotent)
uv run --project cli aico deploy system \
  --tenant-display-name "My Deployment" \
  --admin-full-name "Owner Admin" \
  --admin-pin "1234"

For headless setups you can provide the master password via AICO_MASTER_PASSWORD or --master-password-file.

Contributing

See contributing.md for ways to get involved, contribution etiquette, and project values.

Highlights: - All skillsets welcome (development, design, research, writing, testing, etc.) - Small, atomic commits and clear PRs - Respectful, constructive code reviews

Repository Structure

The AICO repository is organized as a polyglot monorepo, with each major component in its own directory:

aico/
│
├── backend/           # Python FastAPI backend with plugin architecture
│
├── frontend/          # Flutter 3.27+ UI app with encrypted local storage
│
├── cli/               # Python Typer/Rich CLI (v1.1.0, production-ready)
│
├── modelservice/      # Ollama integration service with ZeroMQ
│
├── shared/            # Shared Python libraries (aico.* namespace)
│
├── proto/             # Protocol Buffers and shared API schemas
│
├── config/            # Configuration files and Modelfiles
│
├── docs/              # Documentation (architecture, guidelines, etc.)
│
├── site/              # Built documentation/static site output (generated)
│
├── scripts/           # Development and testing scripts
│
├── .github/           # GitHub workflows, issue templates, etc.
├── LICENSE
├── README.md
├── mkdocs.yml         # MkDocs config for docs
└── (Python deps are managed per component: shared/, backend/, modelservice/, cli/)

Key Points: - Each main component (backend, frontend, studio, cli) is isolated with its own dependencies and tooling. - proto/ contains Protocol Buffer definitions for cross-component communication. - docs/ holds all documentation, including architecture and development guides. - site/ is generated from docs/ for static site hosting.

Studio note: AICO Studio is developed in a separate repository (aico-studio) and deployed independently.

Development Principles

AICO follows strict guidelines for code quality, modularity, privacy, and extensibility. See guidelines.md for details.

Highlights: - Simplicity and readability first - Modular, message-driven architecture - Privacy & security by design - Stateless services: correctness-critical state lives in Postgres and/or NATS/JetStream - Extensible via plugins and clear interfaces

Setting Up Your Environment

Follow these steps to get started with AICO development:

1. Clone or Fork the Repository

Core team: 

git clone git@github.com:boeni-industries/aico.git
Contributors:

  • Fork the repository on GitHub.
  • Clone your fork
git clone git@github.com:<your-username>/aico.git

2. Install Python (3.13+)

AICO Python components require Python 3.13+.

After installation, verify with: 

python --version
# or
py --version
You should see Python 3.13.x.

ℹ️ Storage + Statelessness

The backend is designed to be stateless: correctness-critical state is externalized to Postgres and/or NATS/JetStream.

3. UV Setup (Per-Component Projects)

AICO uses UV for Python dependency management. Each Python component is its own UV project with its own pyproject.toml and uv.lock.

This is required because some components intentionally use conflicting dependency versions (e.g. backend vs modelservice).

Important (Development): isolate runtime config (AICO_CONFIG_DIR)

AICO reads and edits configuration from the runtime config directory (platform-dependent) by default. In development, you should point AICO_CONFIG_DIR to a repo-local path so different checkouts/branches don't share the same config state.

# Example (recommended): keep runtime config inside the repo
export AICO_CONFIG_DIR="$PWD/.aico-dev/config"

# Seed the runtime config directory with schemas/defaults/environments/modelfiles
uv run --project cli aico config init

Install uv globally (required):

pip install uv
# or follow: https://github.com/astral-sh/uv#installation

Initial Setup (CLI project):

# From the repo root

# Verify the CLI runs (uv will resolve the per-project environment)
uv run --project cli aico --help

Key Changes from Previous Setup: - Python dependencies are managed per component: - shared/pyproject.toml - cli/pyproject.toml - backend/pyproject.toml - modelservice/pyproject.toml - shared/ is consumed as an editable path dependency by the other components.

Working with the Workspace:

# Run CLI commands (from repo root)
uv run --project cli aico gateway status
uv run --project cli aico deploy system --help

IDE Setup: Point your IDE to the interpreter inside the component you're working on (e.g. cli/.venv/...).

6. Setting Up the Flutter Frontend

The flutter project scaffolding is present in /frontend.

Install Flutter:

  • Download and install Flutter from the official site for your platform (Windows, macOS, Linux).
  • After installation, check your version (we recommend Flutter 3.27+): 
    flutter --version

Set up platform dependencies:

  • For Android: Install Android Studio and set up the Android SDK.
  • For iOS (macOS only): Install Xcode and set up the iOS toolchain.
  • For web/desktop: Follow Flutter platform setup instructions as needed.

Install dependencies:

cd frontend
flutter pub get

Run the app: 

flutter run
.gitignore: is already configured to exclude build artifacts.

Tip

Use VS Code, Android Studio, or Windsurf with the Flutter/Dart plugins for the best development experience.

7. AICO Studio (separate repository)

AICO Studio is developed in the separate aico-studio repository and deployed independently.

Install Node.js & npm:

  • Download and install the latest LTS version of Node.js from nodejs.org. npm is included.
  • After installation, check your versions (we recommend Node.js 22.x+ and npm 11.x+):
node --version
npm --version

Install Coverage Tools:

For generating HTML coverage reports across all subsystems: 

npm install -g @lcov-viewer/cli

Install dependencies: 

cd studio
npm install

Run the app: 

npm start
# Visit http://localhost:3000

.gitignore: Already configured to exclude build artifacts and node_modules.

Tip: Use VS Code with React/TypeScript extensions for the best development experience.

Building and Running Components

Below are the build and run commands for each major part of the system. Substitute your platform (Windows, macOS, Linux) as appropriate.

Backend + Core + Modelservice (Docker)

Backend (gateway + core) and modelservice run in Docker in local development.

# From repo root
docker compose -f docker/docker-compose.local.yml up --build

CLI (Python CLI)

Run the CLI in development

  • All platforms: 
    # From cli/
uv run aico --help
uv run aico gateway status
uv run aico db init

Build the CLI executable (PyInstaller)

  • All platforms: 
    # From project root
cd cli
uv run pyinstaller aico_main.py --onefile --name aico
# Executable will be in cli/dist/aico(.exe)

Run the built executable

  • Windows: 
    cli\dist\aico.exe
  • Linux/macOS: 
    ./cli/dist/aico

Frontend (Flutter)

  • All platforms: 
    cd frontend
flutter run
  • For desktop: flutter run -d windows (Windows), -d macos (macOS), -d linux (Linux)
  • For web: flutter run -d chrome
  • For mobile: Use flutter devices to list and select your target

Studio (React Admin UI)

  • All platforms: 
    cd studio
npm start
  • Open http://localhost:3000 in your browser if it does not open automatically.

Development Notes

Dependency Management

AICO uses UV per component:

  • CLI: cli/pyproject.toml + cli/uv.lock
  • Backend: backend/pyproject.toml + backend/uv.lock
  • Modelservice: modelservice/pyproject.toml + modelservice/uv.lock
  • Shared: shared/pyproject.toml + shared/uv.lock

When you change dependencies in a component:

uv add <package>
uv lock
uv sync --frozen

Project Structure

The project follows a monorepo structure with shared libraries and unified tooling across all components.

Database Setup

AICO uses a multi-database architecture. PostgreSQL, Loki, and InfluxDB run in Docker containers for consistent deployment across platforms.

🐳 Docker Deployment

PostgreSQL, Loki, and InfluxDB are containerized using Docker for: - Consistent environments across development, testing, and production - Easy version management (PostgreSQL 18.1, Loki 2.9, InfluxDB 2.x) - Isolated dependencies without system-wide installation - Simple cleanup with container removal

Future: Additional components (ChromaDB, analytics services) will be containerized as the architecture evolves.

Prerequisites

Install Docker: - Download and install Docker Desktop for your platform - Verify installation: docker --version - Ensure Docker daemon is running

PostgreSQL Deployment

PostgreSQL stores all core application data (users, conversations, knowledge graph, agency).

Initial Deployment: 

aico deploy pg

This command: 1. Pulls PostgreSQL 18.1 Docker image (if not present) 2. Starts PostgreSQL container with persistent volume 3. Connects to the containerized instance 4. Creates the aico database if it doesn't exist 5. Creates the aico_core schema 6. Applies all schema migrations 7. Sets up initial tables and indexes

Container Details: - Image: postgres:18.1 - Port: 5432 (mapped to host) - Volume: Persistent storage for database files - Network: Docker bridge network for inter-container communication

⚠️ DANGEROUS: Reset Database: 

aico deploy pg --nuke

WARNING: The --nuke flag will: - STOP and REMOVE the PostgreSQL container - DELETE the persistent volume - ERASE ALL DATA permanently - Pull fresh image and recreate container - Apply all migrations to new database

Use cases for --nuke: - ✅ Development: Starting fresh after schema changes - ✅ Testing: Clean slate for integration tests - ❌ NEVER in production - you will lose all user data

Prerequisites: - Docker installed and running - Database credentials configured in config/defaults/postgres.yaml - Password stored in system keyring via aico security setup

Loki Deployment

Loki stores application logs with LogQL query support.

Initial Deployment: 

aico deploy loki

This command: 1. Pulls Loki 2.9 Docker image (if not present) 2. Starts Loki container with persistent volume 3. Configures log retention (default: 30 days) 4. Sets up label-based indexing 5. No authentication required for local development

Container Details: - Image: grafana/loki:2.9.0 - Port: 3100 (mapped to host) - Volume: Persistent storage for logs - Network: Docker bridge network

⚠️ DANGEROUS: Reset Logs: 

aico deploy loki --nuke

WARNING: The --nuke flag will: - STOP and REMOVE the Loki container - DELETE the persistent volume - ERASE ALL logs permanently - Pull fresh image and recreate container

Use cases for --nuke: - ✅ Development: Clear old logs - ✅ Testing: Fresh log baseline - ❌ Use with caution - historical logs are lost

Prerequisites: - Docker installed and running - Loki URL configured in config/defaults/loki.yaml (http://localhost:3100)

InfluxDB Deployment

InfluxDB stores time-series metrics and performance telemetry.

Initial Deployment: 

aico deploy influx

This command: 1. Pulls InfluxDB 2.x Docker image (if not present) 2. Starts InfluxDB container with persistent volume 3. Connects to the containerized instance 4. Creates the aico organization if it doesn't exist 5. Creates the aico_telemetry bucket 6. Sets up retention policies (default: 30 days) 7. Configures API token for writes

Container Details: - Image: influxdb:2-alpine - Port: 8086 (mapped to host) - Volume: Persistent storage for time-series data - Network: Docker bridge network

⚠️ DANGEROUS: Reset Metrics Database: 

aico deploy influx --nuke

WARNING: The --nuke flag will: - STOP and REMOVE the InfluxDB container - DELETE the persistent volume - ERASE ALL metrics permanently - Pull fresh image and recreate container - Reconfigure organization and bucket

Use cases for --nuke: - ✅ Development: Clear old telemetry data - ✅ Testing: Fresh metrics baseline - ❌ Use with caution - historical data is lost

Prerequisites: - Docker installed and running - InfluxDB URL configured in config/defaults/influx.yaml (http://localhost:8086) - API token stored in system keyring

Verification

Check PostgreSQL: 

aico pg tables  # List all tables in aico_core schema
aico pg users   # List users (should be empty initially)

Create Your User Account

After deploying databases, create your user:

aico security create-user

This will: 1. Prompt for your full name and nickname 2. Create a secure PIN 3. Store user in PostgreSQL 4. Set up authentication credentials

Check Loki: 

aico logs tail --lines 10  # Query recent logs from Loki

Check InfluxDB: 

# InfluxDB now stores metrics only (not logs)
curl http://localhost:8086/health  # Check InfluxDB health

Database Configuration

Edit config/defaults/postgres.yaml, config/defaults/loki.yaml, and config/defaults/influx.yaml:

db_name: "aico"
core_schema: "aico_core"
host: "127.0.0.1"
port: 5432
user: "postgres"
# Password stored in keyring

# ---

url: "http://127.0.0.1:8086"
org: "aico"
bucket: "aico_telemetry"
# Token stored in keyring

Troubleshooting

PostgreSQL connection failed: 

# Check if PostgreSQL container is running
docker ps | grep postgres

# View PostgreSQL container logs
docker logs aico-postgres

# Connect to PostgreSQL container directly
docker exec -it aico-postgres psql -U postgres -c "SELECT version();"

# Verify password in keyring
aico security keyring list

# Re-setup credentials
aico security setup

InfluxDB connection failed: 

# Check if InfluxDB container is running
docker ps | grep influx

# View InfluxDB container logs
docker logs aico-influx

# Check InfluxDB health endpoint
curl http://localhost:8086/health

# Verify token
aico security keyring list

Loki connection failed: 

# Check if Loki container is running
docker ps | grep loki

# View Loki container logs
docker logs aico-loki

# Check Loki health endpoint
curl http://localhost:3100/ready

# Test log query
curl -G "http://localhost:3100/loki/api/v1/labels" | jq

Docker issues: 

# Check Docker daemon status
docker info

# List all AICO containers
docker ps -a | grep aico

# Remove stopped containers
docker rm aico-postgres aico-loki aico-influx

# Remove volumes (⚠️ deletes data)
docker volume rm aico-postgres-data aico-lokidata aico-influx-data

Database Setup (Legacy)

AICO uses encrypted databases for all data storage with security by design. The setup process automatically handles directory creation, security initialization, and database configuration.

# Optional (recommended in dev): isolate runtime config per repo/branch
export AICO_CONFIG_DIR="$PWD/.aico-dev/config"

# 1. Initialize AICO configuration directories
aico config init

# 2. Initialize encrypted database (auto-setup security if needed)
aico db init

# 3. Create AI character model (required for conversations)
aico ollama generate eve

# 4. Verify complete setup
aico config show
aico db show
ollama list  # Should show 'eve' model

Step-by-Step Process

1. Configuration Directory Setup

# Initialize all AICO directories (data, config, cache, logs)
aico config init

# Verify directory structure
aico config show

2. Database Initialization

# Create encrypted PostgreSQL database with automatic security setup
aico db init

# Test database connection and encryption
aico db test

# View database configuration and paths
aico db show

Note: The aico db init command automatically sets up master password security if not already configured, eliminating the need for separate aico security setup step.

3. AI Character Model Setup

AICO uses Ollama with custom character definitions (Modelfiles) to create AI personalities. The Eve character is the default AI companion.

# Create the Eve character model from Modelfile
aico ollama generate eve

# Verify the model was created successfully
ollama list
# You should see the base model 'huihui_ai/qwen3-abliterated:8b-v2'

# Test the model (optional)
ollama run huihui_ai/qwen3-abliterated:8b-v2 "Hello, who are you?"

What this does: - Reads the character definition from your runtime config directory ($AICO_CONFIG_DIR/modelfiles/Modelfile.eve) - Seeds/syncs Modelfiles from the repo templates when needed (aico config init) - Ensures the base model is pulled from Ollama - Configures model parameters (temperature, context window, etc.) - Sets up the character's personality and behavior via Modelfile

Character Details: - Name: Eve - Base Model: huihui_ai/qwen3-abliterated:8b-v2 (uncensored, thinking-capable) - Personality: Warm, curious, contemplative companion with genuine thoughts and feelings - Features: Natural conversation style, Ollama 0.12+ native thinking API support - Parameters: num_ctx=8192, temp=0.7, top_p=0.8, top_k=20

Updating the Character: If you modify Modelfile.eve, regenerate: 

aico ollama generate eve --force

For more details, see the Modelfiles README in the repository at config/modelfiles/README.md.

Directory Structure

After setup, you'll have cross-platform directories: 

# Windows Example: %APPDATA%/aico/
# macOS Example: ~/Library/Application Support/aico/
# Linux Example: ~/.local/share/aico/
aico/
├── data/
│   ├── PostgreSQL database              # Main PostgreSQL database (encrypted)
│   ├── PostgreSQL database.salt         # Encryption salt
│   ├── analytics.db         # Analytics database (planned, backend TBD)
│   └── chroma/              # Vector database directory (ChromaDB)
├── config/
│   ├── schemas/             # Configuration schemas (*.schema.json)
│   ├── defaults/            # Default configuration files
│   ├── environments/        # Environment-specific overrides
│   ├── modelfiles/          # Modelfiles (e.g. Modelfile.eve)
│   └── runtime.yaml         # Persisted runtime overrides
├── cache/                   # Application cache
└── logs/                    # Application logs

Configuration Management

AICO uses a hierarchical configuration system with externalized settings:

# View all configuration paths and settings
aico config show

# View database-specific configuration
aico db show

# Get specific configuration values
aico config get postgres.host
aico config get system.paths.directory_mode

Troubleshooting

Setup issues: 

aico config show       # Check directory structure
aico db show          # Check database configuration

Database connection fails: 

aico db status        # Check database status
aico db test          # Test database connection

Security/encryption issues: 

aico security status  # Check security setup
aico security test    # Verify keyring access

For detailed architecture and configuration options, see Data Layer Documentation.

Protocol Buffer Compilation

AICO uses Protocol Buffers for cross-component communication. After making changes to .proto files, you need to regenerate the language-specific code.

Prerequisites

Install the Protocol Buffers compiler: 

# macOS
brew install protobuf

# Ubuntu/Debian  
sudo apt-get install protobuf-compiler

# Windows (via chocolatey)
choco install protoc

Install language-specific plugins: 

# Python
pip install protobuf mypy-protobuf

# Dart (for Flutter frontend)
dart pub global activate protoc_plugin

# JavaScript/TypeScript (for Studio admin interface)
npm install -g protoc-gen-js protoc-gen-grpc-web

Generating Code

Recommended: Use the CLI helper so the correct include paths are selected automatically:

# From the repo root
./aico dev protoc

This runs protoc from the repo root and automatically includes the active CLI venv's site-packages (for Google well-known types).

Note: All commands assume you're starting from the AICO project root directory.

For Python, you must include both the proto directory and your venv's site-packages as -I (include) paths, so that Google well-known types are found.

Python (Backend & Shared):

From the project root, run (adjust the -I path to match the Python environment you're using, e.g. shared/.venv/... or cli/.venv/...):

protoc -I=proto -I=<path-to-site-packages> --python_out=shared/aico/proto proto/aico_core_api_gateway.proto proto/aico_core_common.proto proto/aico_core_envelope.proto proto/aico_core_logging.proto proto/aico_core_plugin_system.proto proto/aico_core_update_system.proto proto/aico_emotion.proto proto/aico_integration.proto proto/aico_personality.proto proto/aico_conversation.proto proto/aico_modelservice.proto
- If you get errors about missing google/protobuf/*.proto files, make sure your venv's site-packages/google/protobuf/ directory contains the .proto files. If not, download them from the official repo and copy them in.

Dart (Flutter Frontend): 

cd proto
protoc -I=. --dart_out=../frontend/lib/generated ./core/*.proto ./emotion/*.proto ./conversation/*.proto ./personality/*.proto ./integration/*.proto

JavaScript/TypeScript (Studio Admin Interface): 

cd proto
protoc -I=. --js_out=import_style=commonjs,binary:../studio/src/generated --grpc-web_out=import_style=commonjs,mode=grpcwebtext:../studio/src/generated ./core/*.proto ./emotion/*.proto ./conversation/*.proto ./personality/*.proto ./integration/*.proto

For detailed protobuf development guidelines, see Protocol Buffers & API Contracts.

Further Reading

This document is a living guide and will be updated as the project grows. If you have suggestions, please open an issue or PR!