Celilo

Celilo is an application-deployment and orchestration tool for opinionated, zone-segmented networks — built to grow a home lab (or any small fleet) from a single Linux box into a multi-zone, internet-facing deployment, one capability at a time.

You describe what you want running; Celilo figures out where it can go, generates standard Infrastructure-as-Code (Terraform + Ansible), and drives the deployment. It orchestrates industry-standard tools rather than replacing them — the generated projects are normal Terraform/Ansible you can read and modify.

Status: early development (alpha). This project recently graduated from a private home-lab repo to a public one. Interfaces, schemas, and module formats change without notice, and there is no stability or backward-compatibility guarantee yet. Use it to learn and experiment, not (yet) to run anything you can't afford to rebuild.

The idea: networks that grow with you

Celilo models a network as up to six zones, but assumes you start with only one and unlock the rest as you add infrastructure:

Zone	Purpose
internal	Secured client network — the one zone you always have.
external	The public internet (unlocked by adding a VPS).
dmz	Internet-reachable services, no VPN required (unlocked by a firewall).
app	More sensitive services, reachable only from dmz + management.
secure	The most sensitive services, reachable only from app + management.
management	Privileged-access clients.

A module (e.g. a public website, DNS, a firewall) declares which zones it prefers and which it can tolerate. Deploy a public-web module on a box with no firewall and it still runs on internal; add a firewall and a border gateway later and Celilo offers to promote it into the dmz with real TLS certificates. Modules share data through capabilities — a firewall module provides the zones and port-forwarding a website module requires. See VISION.md, PRINCIPLES.md, and GLOSSARY.md for the full model, and design/ for the architecture documents.

Tech stack

• Core: TypeScript on Bun, SQLite + Drizzle ORM, a SQLite-backed event bus
• Remote API: drive the CLI on the management server over SSH (celilo --remote) — a typed, streamed NDJSON protocol with per-operation authz; no new inbound port (see openspec/changes/replace-ssh-cli-api/proposal.md)
• Generated IaC: Terraform (HCL) + Ansible (YAML)
• CLI/TUI: Ink (React 19) terminal UI (a React/Vite/Tailwind web UI is planned, not yet built)
• Tooling: Biome (lint/format), Vitest/bun test

Repository layout

apps/celilo/      # the Celilo CLI + backend (TypeScript/Bun)
modules/          # deployable modules (caddy, dns, firewall, forgejo, …)
packages/         # shared workspace packages (capabilities, cli-display, e2e, …)
design/           # architecture & technical design documents

Quick start

bun run setup                       # installs workspace + per-module script deps
cd apps/celilo
bun run src/cli/index.ts --help     # explore the CLI
bun test                            # unit tests

Use bun run setup, not a bare bun install. Each module under modules/*/scripts has its own dependencies that the workspace install does not cover; bun run setup installs both. Skipping it makes ~10 unit tests fail with Cannot find module '@celilo/capabilities'.

The CLI walks you through initializing a system, adding machines or container services, importing modules, and deploying them. Start with system init and --help on each subcommand.

License

AGPL-3.0 © Peter Banka (psbanka). If you run a modified version as a network service, the AGPL requires you to make your changes available to its users.