ChimerAI

A modular self-hosted AI homelab stack for agents, MCP tools, automation, and secure operations.

ChimerAI is an early-stage infrastructure project for people who want their AI tools to work together instead of living as disconnected Docker examples.

It is inspired by mature homelab projects like Saltbox, but it targets the AI-era version of that problem: agents, MCP servers, model providers, workflow automation, memory, ingress, auth, backups, and diagnostics under one reproducible control plane.

Quick Start

Current state: ChimerAI can bootstrap local control tooling, create an encrypted private config file, validate the host, and deploy/remove an early single-server stack with Traefik, Authentik, OpenClaw, and Open WebUI.

git clone https://github.com/vpatel9202/ChimerAI.git
cd ChimerAI
./install.sh
chimerai config init
chimerai validate

When you are ready to deploy the current proof of concept:

chimerai apply

The default public-ingress template expects a real domain pointed at the host, ports 80 and 443 reachable from the internet, and chimerai_acme_email set for Let's Encrypt. The template starts with Let's Encrypt staging enabled so first runs do not burn production certificate rate limits.

To remove ChimerAI-managed services:

chimerai remove

The installer does not deploy services. It only prepares local tooling, links the chimerai command into ~/.local/bin, installs Python/Ansible dependencies, and installs sops/age if they are missing.

See Installation for details and troubleshooting.

Current Capabilities

Implemented today:

• repo-local bootstrap with install.sh;
• chimerai CLI wrapper for config initialization, editing, validation, apply, and remove;
• SOPS + age encrypted private config at inventories/local/chimerai.sops.yaml;
• Ansible roles for common, docker, networks, traefik, authentik, openclaw, diag, and open_webui;
• Traefik public ingress with Let's Encrypt HTTP-01 certificate management;
• Authentik as the shared forward-auth layer for Traefik-routed apps;
• OpenClaw gateway deployment plus chimerai openclaw onboard helper;
• Docker Compose output for Open WebUI in a predictable deployment directory;
• app-local bind-mounted state under the configured state root;
• GitHub Actions validation for shell syntax, Ansible syntax, and safe dry-run.

Still rough or intentionally incomplete:

• backup and restore workflows;
• MCP server roles;
• model provider abstraction or inherited API key configuration.
• fully automated Authentik provider/application wiring.

Status

ChimerAI is in design/prototype stage. It is being built in public from lessons learned on a real private homelab deployment, but the public repo is not yet a complete turnkey AI stack.

Primary test target:

• Ubuntu 24.04
• Docker with Compose v2
• single-server homelab or VPS

Use it now if you are comfortable reading the code and helping shape the project. If you want a fully supported appliance, wait for a later public alpha.

Why ChimerAI?

Self-hosted AI has a packaging problem.

There are excellent tools for chat, local models, workflow automation, RAG, browser control, task management, calendars, memory, and MCP. But deploying them as a coherent system still usually means manually combining:

• Docker Compose files from many projects;
• reverse proxy and TLS configuration;
• authentication and SSO;
• model provider secrets;
• local and API model routing;
• MCP server wiring;
• OAuth flows for calendars, tasks, email, and files;
• backup and restore boundaries;
• health checks and diagnostics;
• safe remote access.

ChimerAI aims to make that stack reproducible, inspectable, and operable.

Architecture

ChimerAI is Ansible-first and Docker Compose-native.

Ansible owns lifecycle work:

• host bootstrap;
• users, directories, permissions, and packages;
• Docker and network setup;
• config and secret template rendering;
• app lifecycle commands;
• firewall and ingress setup;
• backups and restore workflows;
• diagnostics and validation.

Docker Compose stays visible because homelab operators need to debug real containers with familiar tools. ChimerAI should generate understandable Compose, not hide services behind an opaque abstraction.

The current shape is:

.
├── install.sh
├── bin/
│   └── chimerai
├── ansible.cfg
├── chimerai.yml
├── inventories/
│   └── examples/
├── roles/
│   ├── common/
│   ├── docker/
│   ├── networks/
│   ├── traefik/
│   ├── authentik/
│   ├── openclaw/
│   ├── diag/
│   └── open_webui/
├── templates/
│   └── config/
└── docs/

Planned role categories include ingress/auth, remote access, agent runtimes, MCP servers, model gateways, local models, automation, memory, document ingestion, backups, and operations tooling.

Key Decisions

ChimerAI makes a few opinionated choices.

• Ansible instead of a custom orchestrator: Ansible is boring, inspectable, and already good at host state. The chimerai CLI is only a wrapper around common workflows.
• Docker Compose instead of Kubernetes: most homelab AI services already publish Compose examples, and Compose is easier for single-server operators to debug.
• SOPS + age for secrets: users get one private YAML config file while sensitive values stay encrypted at rest.
• App-local state instead of opaque Docker volumes: runtime files should be easy to find, inspect, back up, and migrate.
• Provider-neutral agent instructions: Codex, Claude, Gemini, local models, and other coding agents should all read the same project policy.

See Architecture Decision Records for the durable rationale.

Common Commands

Bootstrap local tooling:

./install.sh

Create encrypted local config:

chimerai config init

Edit encrypted config:

chimerai config edit

Validate the host and config:

chimerai validate

Apply the configured stack:

chimerai apply

Remove ChimerAI-managed services:

chimerai remove

Run the lower-level Ansible validation directly:

uv run ansible-playbook chimerai.yml --check

Run the generated OpenClaw tools container for first-time onboarding:

chimerai openclaw onboard

Documentation

Start here:

• Installation: bootstrap a fresh local checkout.
• Configuration and Secrets: encrypted config, SOPS, age, and editing secrets.
• Inventory Schema: current variable shape.
• Role Contract: expectations for future roles.
• Milestone 2 Stack Plan: first Traefik + Authentik + OpenClaw stack rationale.
• Architecture Decisions: why major choices were made.
• Agent Context: instructions for AI coding agents.

AI-First Development

ChimerAI is intended to be built and operated with AI coding agents as a normal part of the workflow.

The expected pattern is:

1. A human states intent, constraints, and acceptance criteria.
2. A coding agent inspects the repo, proposes or applies a focused change, and runs relevant validation.
3. A human reviews the diff, tests the behavior, and decides what ships.

The project is provider-neutral:

• AGENTS.md is the source of truth for agent behavior.
• CLAUDE.md and GEMINI.md are thin import shims that load AGENTS.md; they do not define separate policy.
• docs/agents/ contains deeper topic-specific context.
• .local/ is the ignored private workspace convention for local handoffs, private context, and operator-specific to-do lists.

Roadmap

Milestone 0: Project Definition

• Choose project name
• Create initial README
• Define role contract
• Define inventory schema
• Choose initial license
• Add contribution guidelines
• Add provider-neutral agent instructions
• Add local workspace templates
• Add parseable Ansible dry-run skeleton
• Add CI validation for the dry-run skeleton
• Add foundational architecture decision record

Milestone 1: Ansible Proof Of Concept

• Add common role
• Add docker role
• Add networks role
• Add open_webui role
• Add diag role
• Validate a minimal install on Ubuntu 24.04
• Define encrypted single-file configuration with SOPS + age
• Add bin/chimerai wrapper for config init/edit/validate
• Add repo-local bootstrap installer

Milestone 2: First Real Stack

• Choose the first real AI stack role set
• Add ingress profile
• Add authentication profile
• Add the first agent/runtime role beyond Open WebUI
• Add the first MCP server role
• Add backup and restore workflows
• Document a complete fresh-server install

Milestone 3: Public Alpha

• Publish example inventories
• Add issue templates
• Add security policy
• Add comparison guide against existing self-hosted AI stacks

Contributing

ChimerAI is not ready for broad contribution yet, but early design feedback is welcome.

Good early contributions:

• propose role structure improvements;
• identify existing projects worth integrating instead of duplicating;
• suggest app categories and profiles;
• test the current proof of concept;
• improve documentation clarity.

Before proposing role changes, read Role Contract and Inventory Schema.

Name

A chimera is a composite creature. ChimerAI is a composite AI stack: agents, models, tools, automations, memory, and infrastructure blended into one operable system.

License

ChimerAI is licensed under the Apache License 2.0.