# AutoAir

> AutoAir is a visual DAG builder for Apache Airflow 3. DAGs are drawn on a canvas or written in code mode, validated, and saved as readable Python that Airflow loads like any hand-written DAG. It runs inside the Airflow API server as a plugin or as a standalone server, deploys to the DAGs folder, Git (pull requests or direct pushes) or object storage, and authorizes every request through Airflow.

The documentation covers installation (pip extras, the Airflow plugin, the standalone server, Docker Compose and Helm), the builder, the optional AI features and MCP server, administration (configuration, IAM, SSO, policy, audit), deployment guides, extension points and the generated configuration and CLI references. Every page is also available as Markdown in llms-full.txt, and coding agents can search and read the documentation of the installed version over MCP with `autoair docs-mcp` (AutoAir docs MCP page below).

## Getting started

- [What is AutoAir](https://ctolon.github.io/autoair/docs/intro): AutoAir is a visual and code-based DAG builder for Apache Airflow 3 that stores every DAG as a versioned specification and generates readable, validated Python from it.
- [Quick start](https://ctolon.github.io/autoair/docs/getting-started/quick-start): Run AutoAir in local mode, inside an existing Airflow 3, as a Docker Compose demo, or as a standalone server, with the exact prerequisites for each.
- [Build your first DAG](https://ctolon.github.io/autoair/docs/getting-started/first-dag): A step-by-step tutorial that builds the orders_daily DAG (extract, transform, load) on the canvas, schedules it daily, fixes problems, previews the generated code and deploys it.
- [Concepts](https://ctolon.github.io/autoair/docs/getting-started/concepts): The model behind AutoAir - the DagSpec, nodes and edges, task groups, generated code, validation, deploy targets, environments, IAM roles, collaboration and AI.

## Installation

- [Installation overview](https://ctolon.github.io/autoair/docs/installation/overview): Choose between the Airflow plugin, the standalone server and local mode, and find the installation method that fits your environment.
- [Optional extras](https://ctolon.github.io/autoair/docs/installation/extras): Every optional dependency group of the autoair package, what it enables, the settings that turn the feature on, and how to install it with pip or uv.
- [Airflow compatibility](https://ctolon.github.io/autoair/docs/installation/compatibility): Which AutoAir extras can be installed next to each supported Airflow version, the dependency pins behind each gap, and how to run the MCP server when it cannot share Airflow's environment.
- [Local mode](https://ctolon.github.io/autoair/docs/installation/local): Run AutoAir on a workstation with autoair local - no Airflow server, a static operator catalog of the installed packages, and deploys to a local folder or Git.
- [Airflow plugin](https://ctolon.github.io/autoair/docs/installation/plugin): Install AutoAir into an Airflow 3 environment as a plugin, how it integrates with the Airflow 3.0 and 3.1+ UI, the URLs it serves, and how to configure and verify it.
- [Standalone server](https://ctolon.github.io/autoair/docs/installation/standalone): Run AutoAir as its own service with autoair serve next to an Airflow 3 deployment - installation, Airflow URL, sign-in and token verification, DAG delivery, TLS and a container example.
- [Docker Compose](https://ctolon.github.io/autoair/docs/installation/docker-compose): Run the AutoAir demo stack from deploy/compose (Airflow 3 in split components with the plugin, two standalone replicas on PostgreSQL, and opt-in profiles for a load balancer, Redis, the AI service, Ollama, a Gitea deploy target, TLS and tracing), or the single-container setup.
- [Helm](https://ctolon.github.io/autoair/docs/installation/helm): Deploy AutoAir as an Airflow plugin with the official Apache Airflow Helm chart using deploy/helm/values-autoair.yaml, explained setting by setting.
- [Upgrading](https://ctolon.github.io/autoair/docs/installation/upgrading): Upgrade AutoAir in each run mode - the wheel, state database migrations, the operator catalog, frontend assets, compatibility checks and rollback.

## User guide

- [User guide overview](https://ctolon.github.io/autoair/docs/user-guide/overview): Map of the AutoAir user guide, the workbench layout and the differences between the Airflow plugin and the standalone UI.
- [Canvas and workbench](https://ctolon.github.io/autoair/docs/user-guide/canvas): How to build a DAG on the AutoAir canvas, with the palette, inspector, bottom panel, task groups, notes, context menu, auto layout, clipboard, undo and the minimap.
- [Keyboard shortcuts and command palette](https://ctolon.github.io/autoair/docs/user-guide/shortcuts): Every keyboard shortcut of the AutoAir builder on macOS and Windows/Linux, the command palette and its command groups, and the shortcuts sheet.
- [Code mode](https://ctolon.github.io/autoair/docs/user-guide/code-mode): Edit DAGs as Python - the editor modes, the synced code mode of visual DAGs, raw code DAGs, converting between the two, and the read-only environment preview.
- [Field editors](https://ctolon.github.io/autoair/docs/user-guide/editors): The code editors of the AutoAir inspector, built-in IntelliSense, the optional IDE language server, the Validate button and the Markdown editor.
- [Large DAGs](https://ctolon.github.io/autoair/docs/user-guide/large-dags): How the editor handles DAGs with hundreds or thousands of tasks - viewport rendering, the low-detail overview, slower live checks, measured limits, and the settings to tune.
- [Operators and parameters](https://ctolon.github.io/autoair/docs/user-guide/operators-and-parameters): How AutoAir discovers operators, and how to configure them in the inspector with parameter forms, type badges, required fields, defaults, templated fields and pickers.
- [Jinja, XCom and Python](https://ctolon.github.io/autoair/docs/user-guide/jinja-xcom-python): Jinja templates with completion and live preview, XCom references between tasks, Python references, inline functions and inline scripts, and the code AutoAir generates for each.
- [TaskFlow, mapping, branching and loops](https://ctolon.github.io/autoair/docs/user-guide/taskflow-and-loops): TaskFlow decorators supported by AutoAir, dynamic task mapping, branching, task groups, task loops, trigger rules and setup and teardown tasks.
- [Astronomer Blueprint steps](https://ctolon.github.io/autoair/docs/user-guide/blueprints): Insert Astronomer Blueprint templates (airflow-blueprint) as configurable canvas nodes, preview the tasks they render and generate DAGs that call them.
- [Scheduling and assets](https://ctolon.github.io/autoair/docs/user-guide/scheduling-and-assets): The AutoAir schedule editor (presets, cron, intervals, events, timetables and asset conditions), time zones, start and end dates, catchup, asset outlets and inlets, and asset events.
- [Params and trigger forms](https://ctolon.github.io/autoair/docs/user-guide/params-and-trigger-forms): Declare DAG params in AutoAir, preview the Airflow trigger form they produce, trigger runs with them, and call the DAG from outside with ready-made snippets.
- [Human-in-the-loop](https://ctolon.github.io/autoair/docs/user-guide/human-in-the-loop): Configure Airflow's human-in-the-loop operators in AutoAir with the dedicated editor for subject, body, options, defaults, branch mapping, assigned users, timeouts and input forms.
- [Callbacks, retries and deadlines](https://ctolon.github.io/autoair/docs/user-guide/callbacks-retries-deadlines): Configure retries, retry delays, exponential backoff, exception retry policies, notifier callbacks for tasks and DAG runs, and deadline alerts in AutoAir.
- [Connections and Variables](https://ctolon.github.io/autoair/docs/user-guide/connections): Pick and create Airflow connections from the AutoAir builder, use Airflow Variables in templates and code, and map connection and Variable ids per environment.
- [Validation and the Problems panel](https://ctolon.github.io/autoair/docs/user-guide/validation): How AutoAir validates a DAG while you edit it, the server validation pipeline, problem severities and codes, the Problems panel, and how to jump to a finding.
- [Operator templates](https://ctolon.github.io/autoair/docs/user-guide/operator-templates): Save one configured task as a reusable, versioned building block, with locked and required fields that the server enforces.
- [Templates and fragments](https://ctolon.github.io/autoair/docs/user-guide/templates-and-fragments): Start DAGs from built-in or saved templates and reuse groups of tasks as fragments.
- [Marketplace](https://ctolon.github.io/autoair/docs/user-guide/marketplace): Browse signed template marketplaces and install DAG templates and fragments into your template gallery.
- [Versions and diff](https://ctolon.github.io/autoair/docs/user-guide/versions-and-diff): How AutoAir records versions of a DAG, keeps unsaved drafts, compares versions as a spec diff or a code diff, restores old versions and resolves concurrent edits.
- [Deploy](https://ctolon.github.io/autoair/docs/user-guide/deploy): How deploying works in AutoAir, covering deploy targets (local folder, object storage, git), the deploy dialog, pull requests and direct pushes, the governance context, conflicts and post-deploy status.
- [Editing existing Python DAGs](https://ctolon.github.io/autoair/docs/user-guide/editing-python-dags): Keep hand-written DAG files as they are while you edit them on the canvas - source policies, what can be patched, the deploy diff, and DAG files changed outside AutoAir.
- [Reviews and approvals](https://ctolon.github.io/autoair/docs/user-guide/reviews-and-approvals): Review DAG versions, enforce the four-eyes rule for live deploys with iam.require_approval, and audit who approved what.
- [Runs](https://ctolon.github.io/autoair/docs/user-guide/runs): Trigger, backfill, clear and pause DAGs from the builder, follow a run on the canvas, read task logs and XComs, and test tasks in a sandbox.
- [Environments](https://ctolon.github.io/autoair/docs/user-guide/environments): Deploy one DAG to dev, staging and prod with per-environment overlays, connection and Variable aliases, and promotion pull requests.
- [Import and export](https://ctolon.github.io/autoair/docs/user-guide/import-export): Bring existing Python and YAML DAGs into AutoAir, export DAGs as Python, Airflow YAML, dag-factory YAML or AutoAir spec JSON, and see what survives a round trip.
- [Real-time collaboration](https://ctolon.github.io/autoair/docs/user-guide/collaboration): Edit one DAG with other people at the same time, with live presence, shared edits and per-user undo.
- [Multi-team](https://ctolon.github.io/autoair/docs/user-guide/multi-team): Assign DAGs to teams, give each team its own deploy target, scope connection, pool and Variable pickers, and enforce team prefixes.

## AI

- [AI features](https://ctolon.github.io/autoair/docs/ai/introduction): What AutoAir's AI features do, what data they send to a model, and the minimum configuration, feature flags and permissions needed to turn them on.
- [Providers and models](https://ctolon.github.io/autoair/docs/ai/providers): Configure the LLM provider, models, credentials, per-user models and embeddings for AutoAir's AI features.
- [Assist features](https://ctolon.github.io/autoair/docs/ai/assist): Generate, edit, explain, review, scan, optimise and fix DAGs with AI, review proposals as diffs, generate deploy messages and run the Airflow upgrade assistant.
- [AI writers and agent runtimes](https://ctolon.github.io/autoair/docs/ai/writers): The specialised code writers with their validate-and-repair loop, and the pydantic-ai agent runtime with its budgets.
- [Retrieval, research and knowledge](https://ctolon.github.io/autoair/docs/ai/research-and-knowledge): How AutoAir's AI finds reference material (hybrid retrieval, reranking, air-gapped and online research) and how administrators steer it with the knowledge base, prompt overrides, project rules and memory.
- [Documentation knowledge base](https://ctolon.github.io/autoair/docs/ai/knowledge-base): Retrieval over the official Apache Airflow, provider, Helm chart, airflowctl and Astronomer documentation for AutoAir's agents, MCP clients, the admin panel and the CLI, online or air-gapped.
- [Knowledge base sources and versions](https://ctolon.github.io/autoair/docs/ai/knowledge-base-sources): Which documentation the knowledge base indexes - components, installed or all providers, version selection, the source kinds and formats - and how refreshes stay incremental.
- [Knowledge base without internet access](https://ctolon.github.io/autoair/docs/ai/knowledge-base-air-gapped): Feed the documentation knowledge base on an air-gapped installation from a corporate git mirror, object storage, a local folder, an internal HTTP mirror or a signed bundle built on a connected machine.
- [Knowledge base stores](https://ctolon.github.io/autoair/docs/ai/knowledge-base-stores): Where the documentation index lives - the dependency-free local SQLite store, PostgreSQL with pgvector, or Elasticsearch - with setup, TLS and multi-replica notes.
- [Tuning the knowledge base](https://ctolon.github.io/autoair/docs/ai/knowledge-base-tuning): Chunking, retrieval, embeddings and reranking settings of the documentation knowledge base, with their defaults and trade-offs.
- [Knowledge base security](https://ctolon.github.io/autoair/docs/ai/knowledge-base-security): How the documentation knowledge base limits outbound requests, handles credentials, treats retrieved text in prompts and who may search or manage it.
- [Guardrails and AI audit](https://ctolon.github.io/autoair/docs/ai/guardrails): The guardrail pipeline every model call passes, the built-in and external guardrails, token and cost limits, and the AI audit log.
- [Separate AI service](https://ctolon.github.io/autoair/docs/ai/ai-service): Run AutoAir's AI API and MCP server as their own process with autoair ai-serve, and how the main server proxies and authenticates requests to it.
- [MCP server and client](https://ctolon.github.io/autoair/docs/ai/mcp): Connect Claude Desktop, Claude Code, Cursor or VS Code to AutoAir's MCP server, run it in the app, the AI service or standalone, and let AutoAir's agents use external MCP servers.
- [AutoAir docs MCP](https://ctolon.github.io/autoair/docs/ai/docs-mcp): Give coding agents such as Claude Code, Cursor, OpenCode and Codex CLI search and read access to the AutoAir documentation over MCP, offline and matched to the installed version.
- [Chat assistants](https://ctolon.github.io/autoair/docs/ai/assistants): The developer and admin chat assistants, what they can see and do, how a turn runs, threads, proposals, and their ai.assistants settings.
- [Troubleshooting runs with AI](https://ctolon.github.io/autoair/docs/ai/troubleshooting): Analyze a failed DAG run or task instance with AI, choose what the agent may read, review the root-cause report and apply a fix through the normal deploy pipeline.
- [Tool-call approval](https://ctolon.github.io/autoair/docs/ai/tool-approval): How AutoAir's agents pause before a tool that changes something, how you approve or deny each call, and the ai.approvals settings.
- [AI architecture](https://ctolon.github.io/autoair/docs/ai/overview): How AutoAir's AI backend is built - request flow, in-process versus separate service, pydantic-ai models and streaming, the agent runtime, guardrails, retrieval, writers and the design decisions behind them.

## Administration

- [Administration overview](https://ctolon.github.io/autoair/docs/admin/overview): A map of the administration guide and a production checklist for running AutoAir as an Airflow plugin or a standalone server.
- [Configuration](https://ctolon.github.io/autoair/docs/admin/configuration): How AutoAir reads its settings from arguments, environment variables, .env and configuration files, how secrets are handled, and how to inspect the effective configuration.
- [Feature flags](https://ctolon.github.io/autoair/docs/admin/feature-flags): Every features.* switch, what it turns off in the API, the CLI and the UI, and how it interacts with the allow_python_code policy switch.
- [Identity and access management](https://ctolon.github.io/autoair/docs/admin/iam): How Airflow authenticates AutoAir users, how AutoAir permissions and roles are derived from Airflow, and how to configure role mapping, custom views, approvals and direct pushes.
- [Sign-in, SSO and sessions](https://ctolon.github.io/autoair/docs/admin/sso): How users sign in to AutoAir with their Airflow session, an Airflow username and password, or a token; how sessions are refreshed and ended; cookie and CSRF rules; and the sign-in rate limit.
- [TLS and HTTP headers](https://ctolon.github.io/autoair/docs/admin/tls-and-headers): HTTPS and mutual TLS for autoair serve, running behind a reverse proxy with trusted forwarded headers, the security headers and Content-Security-Policy, CORS, and request limits.
- [Database (state store)](https://ctolon.github.io/autoair/docs/admin/database): Where AutoAir keeps its own state, the file, SQLite and PostgreSQL backends, connection URLs and TLS, schema migrations with autoair db, and what is stored where.
- [Scaling and replica safety](https://ctolon.github.io/autoair/docs/admin/scaling): Running several AutoAir workers or replicas safely - what state is shared, what stays per process, how co-editing rooms are shared, and which keys must be the same everywhere.
- [Admin panel](https://ctolon.github.io/autoair/docs/admin/admin-panel): The admin panel's tabs - overview, audit browser, users, AI usage, AI rules, MCP servers, templates, approvals, database, caches and configuration - with the permissions each action needs.
- [Policy](https://ctolon.github.io/autoair/docs/admin/policy): Organisation policy for DAGs built with AutoAir - the policy switches and pattern rules, secret detection, Python code restrictions, declarative rules, Open Policy Agent, and every point where policy is enforced.
- [Audit](https://ctolon.github.io/autoair/docs/admin/audit): What AutoAir records in its audit trail (deploys, reviews, permission denials, administrative actions) and its AI audit log, the audit sinks (file, database, log, OpenTelemetry), how to browse and export records, and retention.
- [Observability](https://ctolon.github.io/autoair/docs/admin/observability): Logging, the health and readiness endpoints, Prometheus metrics, OpenTelemetry tracing, and what to alert on when running AutoAir in production.
- [Backup and restore](https://ctolon.github.io/autoair/docs/admin/backup-restore): What to back up for each state backend and deploy target, which keys must be preserved, and how to restore AutoAir and verify the result.

## Deployment guides

- [Deployment overview](https://ctolon.github.io/autoair/docs/deployment/overview): Choose how to run AutoAir in production, where generated DAGs go, where AutoAir keeps its own state and which supporting services you need.
- [Kubernetes reference architecture](https://ctolon.github.io/autoair/docs/deployment/kubernetes): Components, replica counts, probes, state and network flows for running AutoAir with Airflow 3 on Kubernetes.
- [Kubernetes with Kustomize](https://ctolon.github.io/autoair/docs/deployment/kustomize): Deploy the standalone AutoAir server and its optional validator, AI and MCP services to Kubernetes from the Kustomize base, components and overlays in deploy/kustomize.
- [Plugin with the Airflow Helm chart](https://ctolon.github.io/autoair/docs/deployment/helm-plugin): Build an Airflow image with AutoAir and deploy it as a plugin with the official Apache Airflow Helm chart using deploy/helm/values-autoair.yaml.
- [Git bundles and git-sync](https://ctolon.github.io/autoair/docs/deployment/git-bundles): Deploy AutoAir DAGs to a git repository that Airflow reads through a GitDagBundle or a git-sync sidecar, with pull requests or direct pushes.
- [Object storage](https://ctolon.github.io/autoair/docs/deployment/object-storage): Deploy AutoAir DAGs to an S3 or GCS prefix that Airflow reads through an object-storage DAG bundle, and keep AutoAir state on object storage.
- [Standalone behind a reverse proxy](https://ctolon.github.io/autoair/docs/deployment/standalone-proxy): Run autoair serve behind nginx, Traefik or another reverse proxy with correct forwarded headers, WebSockets, unbuffered AI streaming and public URLs.
- [PostgreSQL for AutoAir state](https://ctolon.github.io/autoair/docs/deployment/postgres): Store AutoAir's own state in PostgreSQL, separate from Airflow's metadata, with migrations, TLS, connection pooling and multi-replica behaviour.
- [Deploying the separate AI service](https://ctolon.github.io/autoair/docs/deployment/ai-service): Run autoair ai-serve as its own deployment, point the main server at it and share configuration, secrets and state between them.
- [Isolated import checks and test runs (validator service)](https://ctolon.github.io/autoair/docs/deployment/validator-service): Run the DagBag import checks and the task/DAG test runs of untrusted DAG code in a separate, locked-down validator service (autoair validator-serve) instead of the Airflow API server.
- [Air-gapped installation](https://ctolon.github.io/autoair/docs/deployment/air-gapped): Install and run AutoAir without internet access - offline wheels, bundled UI assets, a prebuilt operator catalog, local logos, an internal marketplace, self-hosted LLMs and outbound controls.

## Extending

- [Extending AutoAir](https://ctolon.github.io/autoair/docs/extending/overview): The extension points of AutoAir - operator discovery, catalog sources, custom node kinds, templates and the marketplace, the REST API, the DAG spec and MCP.
- [Custom operators](https://ctolon.github.io/autoair/docs/extending/custom-operators): Make in-house and third-party Airflow operators appear in AutoAir's palette through static discovery of folders, packages, distributions, modules and files.
- [Operator packages and metadata](https://ctolon.github.io/autoair/docs/extending/operator-metadata): Make an operator package look first-class in AutoAir's palette - palette groups, icons, parameter widgets, examples and docs links - from the package itself or from AutoAir's configuration.
- [Catalog sources](https://ctolon.github.io/autoair/docs/extending/catalog-sources): Feed AutoAir's operator catalog from your own code through the autoair.catalog_sources entry point.
- [Custom node kinds](https://ctolon.github.io/autoair/docs/extending/node-sdk): Add node kinds with their own configuration form and code generation through the autoair.node_kinds entry point, the custom node template and the frontend registry.
- [Publishing a marketplace](https://ctolon.github.io/autoair/docs/extending/marketplace): Publish a signed marketplace index of DAG templates, fragments and extension packages with autoair marketplace keygen and build, and connect AutoAir to it.
- [REST API](https://ctolon.github.io/autoair/docs/extending/rest-api): Authenticate against AutoAir's REST API, find the base path for plugin and standalone mode, get the OpenAPI document and automate validation, deploys and runs with curl.
- [Spec format](https://ctolon.github.io/autoair/docs/extending/spec-format): The DagSpec JSON document AutoAir stores for every DAG - its JSON Schema, top-level fields, nodes, edges, groups, params, tagged values and versioning.
- [MCP integration](https://ctolon.github.io/autoair/docs/extending/mcp-integration): Integrate AI agents and tools with AutoAir through its Model Context Protocol server - endpoints, authentication, safety switches and when to prefer it over the REST API.

## Reference

- [Configuration reference](https://ctolon.github.io/autoair/docs/reference/configuration): Every AutoAir setting: environment variable, configuration-file key, type, default, description and secret flag.
- [Command-line reference](https://ctolon.github.io/autoair/docs/reference/cli): Every autoair command and option - servers, validation and code generation, import and export, custom node scaffolding, catalog, marketplace, IAM, configuration and database commands - with exit codes and examples.

## Project

- [Security model](https://ctolon.github.io/autoair/docs/security/overview): How AutoAir authenticates and authorises users, where DAG code executes, how secrets are handled, what the AI features can do, and a hardening checklist for production.
- [Security and vulnerability reporting](https://ctolon.github.io/autoair/docs/security/reporting): How to report a vulnerability in AutoAir privately, what to include, the response timeline, supported versions and what is in scope.
- [Troubleshooting FAQ](https://ctolon.github.io/autoair/docs/troubleshooting/faq): Causes and fixes for common AutoAir installation, startup, sign-in, validation, deploy and multi-replica problems, keyed by the messages you see.
- [Development](https://ctolon.github.io/autoair/docs/contributing/development): Set up a development environment for AutoAir, run the checks and tests, follow the code style and submit a pull request.
- [Documentation](https://ctolon.github.io/autoair/docs/contributing/documentation): How the AutoAir documentation site is built - Docusaurus layout, generated reference pages, the API reference, screenshots and videos, checks, versioning and publishing.
- [Roadmap](https://ctolon.github.io/autoair/docs/roadmap): What AutoAir 0.1.0 ships, what is planned or under consideration, and how to propose a feature.

## Optional

- [Full documentation text](https://ctolon.github.io/autoair/llms-full.txt): every page above as Markdown, in this order
- [Documentation MCP server](https://ctolon.github.io/autoair/docs/ai/docs-mcp): search_autoair_docs and read_autoair_doc for coding agents (`uvx --from 'autoair[mcp]' autoair docs-mcp`)
- [REST API reference](https://ctolon.github.io/autoair/api): the OpenAPI description of the AutoAir server, rendered
- [OpenAPI document](https://ctolon.github.io/autoair/openapi.json): the same API as JSON
- [Release notes](https://ctolon.github.io/autoair/blog): changes per release