Skip to main content
When developing Apache Airflow® Dags locally using AI agents, you need to give your agents a way to test their Dag changes in an Airflow environment. The easiest way for humans and AI agents alike to run Airflow on your computer is by using the Astro CLI, which gives you a fully functional Airflow environment, as well as options to test your Dag code. While the Astro CLI is freely available and you don’t need to be an Astronomer customer to install and use it, you can use additional functionality if you have an Astronomer account.
The Astro CLI contains the astro otto command, which lets you interact with Otto, Astronomer’s data engineering agent. You can run Otto with models from Anthropic, OpenAI, and Google, and it’s available as part of the free Astro trial. See Otto overview for more information.
For a hands-on demo of using AI agents in local data engineering, watch the recording of the Local data engineering in the agentic era webinar.

​
Assumed knowledge

To get the most out of this guide, you should have existing knowledge of:

​
Install the Astro CLI

You can install the Astro CLI using Homebrew or directly with curl.
If you installed the Astro CLI previously, rerun the install command to upgrade to the latest version and access all commands mentioned in this document.

​
Create and start an Airflow project

Use the astro dev init command to create a full Airflow project, including an example Dag, in any empty folder on your computer. Start the project with astro dev start in one of two modes.
Container mode runs Airflow in five containers, one for each core component (Docker or Podman required):
  • Scheduler: Monitors Dags and task instances, and schedules a task to run as soon as its dependencies are fulfilled, using the LocalExecutor, which runs tasks inside the scheduler process itself. This is the container you want to use as a dev container when developing Airflow Dags. See Set up your IDE for data engineering.
  • API server: A FastAPI server that serves the Airflow UI and the Airflow REST API. It also allows workers to interact with the metadata database through an internal API.
  • Dag processor: Parses the Dag files in your project and stores a serialized version of each Dag in the metadata database.
  • Metadata database: Stores operational information for Airflow, such as serialized Dags and the history of Dag runs and task instances. The Astro CLI in container mode uses Postgres for this database.
  • Triggerer: Runs asynchronous triggers for deferrable operators and event-driven scheduling.
See Apache Airflow components for how these components interact with each other.
You can still write Airflow Dags even if you can’t install the Astro CLI on your computer. Astro includes the Astro IDE, an in-browser Airflow development environment, where you can write Dags (with optional assistance from Otto), push them to a test Deployment, and commit them to a Git repository. The Astro IDE is included in every free Astro trial.

​
Container mode vs standalone mode

The Airflow UI is where you view Dag runs, trigger Dags manually, and inspect task logs. By default, astro dev start runs a built-in reverse proxy that serves the Airflow UI at <project>.localhost:6563, based on your project folder name. This applies in both container mode and standalone mode, and lets you run multiple Airflow projects at the same time without manually managing ports. Use astro dev start --no-proxy to serve the Airflow UI directly at localhost:8080 instead. See astro dev proxy for more information. The first Airflow project you start is still available at localhost:8080 even with the proxy enabled. If you start an additional project while the first one is still running, that project gets a random port instead and is only reachable through its own <project>.localhost:6563 address. See Standalone mode in the astro dev start reference for more information. Astronomer recommends container mode unless you can’t run Docker or Podman.

​
Astro CLI commands for local development

The Astro CLI has many commands for your AI agent (and you) to interact with your Airflow environments that run locally and on Astro. The following commands are especially useful when working locally:
The astro dev run command can run any Airflow CLI command. Replace airflow with astro dev run. If you have an Astro account, you have access to many more commands that interact with Deployments on Astro. Otto, Astronomer’s data engineering AI agent, uses a large language model (LLM) gateway running on Astro, which is why you need to sign in to work with Otto.

​
Restrict agent commands

Most AI coding agents can call the command-line tools already installed on your computer. If you allow your harness to run Bash commands without human approval, for example in Claude Code’s auto mode, where a classifier by Anthropic decides whether a command appears to be safe, your agent can run CLI commands that have unintended consequences. Agent harnesses typically offer you a way to give more fine-grained permissions for specific CLI commands. Claude Code, for example, defines command permissions in settings.json under a permissions object with three lists:
  • allow: Commands Claude Code runs without asking
  • deny: Commands Claude Code never runs, even if a broader allow rule matches
  • ask: Commands Claude Code confirms with you before running
A deny rule always overrides a matching allow rule. For example, this configuration lets Claude Code run any astro dev sub-command without asking, but requires confirmation before it runs astro deploy:
Any commands that don’t match a rule use the current general setting, for example asking for permission if the harness is in manual mode and potentially running without asking for approval if the harness is in auto mode.
This example is for Claude Code. If you’re using another harness such as OpenAI Codex or Google Gemini CLI, you have different options to restrict CLI command usage. See the relevant harness documentation for more information.