Home / Docs / Overview

Overview & architecture

Yggdrasil is a self-hosted control plane: you describe what you want as manifests, and it executes — orchestrating workflows, talking to your systems through pluggable integrations, and extending every edge with surfaces. It all runs on your infrastructure.

What a control plane is

A catalog shows your systems. Yggdrasil goes further: it operates them. Instead of a read-only layer over your infra, it's the control plane that takes declarative intent and makes it real — versioned, auditable and reversible.

Think of the Norse world-tree the project is named after: a single trunk connecting many realms. Yggdrasil is that trunk — the one place where manifests, execution, integrations and identity meet, without coupling any of your systems to one another.

The pieces

The product is a small set of components with cleanly separated roles:

Core engine

The brain with the authority: it holds your versioned manifests, runs workflows, enforces auth and exposes the API. Every business decision lives here.

CLI

The binary you drive it with: init, apply, run, install, new. It doesn't re-implement logic — it calls the API.

Integration adapters

Independent workers that know how to talk to one external system — AWS, Grafana, Stripe… They plug into the core through an explicit contract.

Surfaces

Extension edges — a UI, an API, an MCP server, a bot — that attach to an integration or to the core engine itself.

The flow

An intent always travels the same path: you express it, the core decides, the adapter acts, your system moves.

The CLI never touches your systems directly: it talks to the core, which validates the manifest, records the version and dispatches the work to the right adapter. The adapter executes and returns the result through the same contract.

Manifests at the center

Everything in Yggdrasil is a versioned manifest — workflows, integration types, instances, teams. You create them with apply, compare them with diff, inspect them with get/describe and undo them with rollback. It's real GitOps for operating your platform.

Start with Manifests to understand the declarative model, then Workflows & runs to see how they turn into execution.

Principles

Self-hosted
Runs on your cluster, your VPC, your Postgres. No data crosses a third party's boundary.
Declarative
You describe the desired state; the core reconciles. Versions and history come for free.
Explicit contract
Every adapter publishes what it can do — capabilities, schemas and version. The core validates before it executes.
Lego principle
Integrations and surfaces are interchangeable pieces. Swap a provider without rewriting the workflow.
Authority in the core
The CLI and surfaces are thin. The business decision lives only in the core engine.

Where to start

If you want to get hands-on right now, head to Self-hosting & first steps — one yggdrasil init brings up Postgres, the core engine and adapters in a single command. If you'd rather understand the model first, follow the order in the sidebar.