Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/BabySid/aether/llms.txt

Use this file to discover all available pages before exploring further.

Aether is a Go library for building workflow orchestration systems. It implements the Graph Workflow Protocol (aether/v1) — a declarative protocol that expresses workflows as versioned JSON documents with typed resources, following the Kubernetes resource model. The engine handles DAG scheduling, loop iteration, conditional branching, retry and timeout policies, cron-triggered runs, and suspend/resume patterns. Everything else — state persistence, task dispatch, expression evaluation, secrets, artifacts — is delegated to pluggable implementations you supply at startup.

​
What Aether is

Aether is a pure scheduler. It reads a workflow document, determines which tasks are ready to run, dispatches them to workers through a broker.TaskBroker, and reacts to completions by re-evaluating the graph. It never contains execution logic of its own. This separation is intentional and strict: the engine is topology-agnostic, meaning your workers can run in the same goroutine, in a separate process, or on remote machines without changing a line of engine code. The protocol it implements — apiVersion: aether/v1 — is the first-class contract. Workflow definitions are portable documents, not Go code. The engine is one possible runtime for those documents; a different runtime could interpret the same JSON.

​
Protocol-first philosophy

Aether follows a protocol-first, not framework-first design. Rather than providing base structs to subclass or interfaces to embed, it defines a document format: 
{
  "apiVersion": "aether/v1",
  "kind": "Workflow",
  "metadata": { "name": "my-pipeline" },
  "spec": {
    "entrypoint": "main",
    "templates": [
      {
        "dag": {
          "name": "main",
          "tasks": [
            { "name": "step-a", "template": "task-a" },
            { "name": "step-b", "template": "task-b", "dependencies": ["step-a"] }
          ]
        }
      }
    ]
  }
}
The workflow definition is the contract. The engine interprets it at runtime. Because the protocol and the runtime are separate, you can version and migrate workflow documents independently of the engine, run the same document against different engine configurations, and test workflow logic without running any infrastructure.

​
Why Aether exists

Most workflow libraries conflate scheduling with execution: they provide a task runner that also decides the execution order. Aether draws a hard boundary between these two concerns. The engine’s responsibilities are narrow:
  • Resolve which tasks in a DAG are ready to run (all dependencies satisfied)
  • Dispatch them to workers via the broker
  • Receive completion results and advance the graph
  • Enforce retry policies, deadlines, and concurrency limits
Everything outside that boundary — how tasks actually run, where state lives, how IDs are generated, how secrets are fetched — is provided by you through interfaces injected at construction time. This means you can embed Aether in a monolith with an in-memory store, or deploy it alongside a distributed queue and a database-backed store, using exactly the same engine code.
The core engine (package aether) has zero external dependencies. All infrastructure concerns are injected through interfaces — the engine never imports third-party packages directly.

​
Resource types

The protocol defines three top-level resource kinds:
KindPurpose
WorkflowA one-shot workflow run submitted immediately
CronWorkflowA workflow definition triggered on a cron schedule
WorkflowTemplateA reusable named template library (referenced by name in Workflow specs)
Each resource follows the same envelope structure — apiVersion, kind, metadata, spec — making the format predictable and consistent with the Kubernetes resource model that many engineers already know.

​
Template types

Inside a workflow spec, templates define the executable units. There are three template types:
Template typeWhat it does
dagDeclares a directed acyclic graph of tasks with explicit dependencies edges. Tasks with no unmet dependencies run in parallel.
taskA leaf executor invocation. Specifies an executor.Plugin type, input parameters, and expected output parameters.
loopIterates over a static items list, a dynamic itemsFrom reference, or a repeatCondition expression. Each iteration runs as a child scope.
Templates are composable: a dag can contain tasks that reference loop templates, which contain tasks that reference inner dag templates, arbitrarily deep (up to the configured maxNestedDepth, default 3, max 10).

​
Key architectural properties

Zero external dependencies in the core. The package aether engine imports only standard library and its own sub-packages. Every infrastructure concern is behind an interface. Hexagonal architecture. Dependencies flow inward — implementations depend on the core engine, never the reverse. Each interface lives in its own package with a minimal surface area. Topology-agnostic. There is no built-in concept of “local” vs “remote” workers. That distinction lives entirely in your broker.TaskBroker and store.Store implementations. Phase ownership. The engine is the sole writer of phase values (Created → Ready → Running → Succeeded | Failed | Error | Timeout | Skipped | Cancelled). Executors return integer ExecCode values; the engine maps them to phases. PhaseSkipped and PhaseCancelled are exclusively engine semantics — executors cannot set them directly. Fat task assignments. The broker.TaskAssignment struct carries everything a worker needs to execute a task: resolved inputs, secrets, artifacts, executor type, and schema. Workers never need to call back into the store.Store.

​
When to use Aether

Aether is a good fit when:
  • You need DAG-based workflow scheduling embedded in a Go service
  • You want the workflow protocol and the infrastructure to be independently replaceable
  • You need to bring your own state store, message broker, and executor fleet
  • You want first-class support for suspend/resume (human approval gates, external callbacks)
  • You need cron-triggered workflows with concurrency policies
Aether may not be the right choice when:
  • You need a fully managed, hosted workflow platform with a UI out of the box
  • Your workflows are simple linear pipelines that don’t require DAG scheduling
  • You want to avoid writing adapter code for your infrastructure components

Quickstart

Wire up the engine and run your first workflow in under ten minutes

Architecture

Understand the hexagonal design and all ten extension interfaces

Workflow model

Deep dive into resources, templates, and the protocol schema

Extension points

Implement custom executors, stores, brokers, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us